OPERATING SYSTEM 
REFERENCE MANUAL 

for the LISA' 



CONTENTS 



Chapter l 
INTRODUCTIGN 

1.1 The Main Functions 1-3 

1.2 Using the OS Functions 1-3 

1.3 The File system 1-4 

1.4 Process Management 1-6 

1.5 Memory Management 1-7 

1.6 Exceptions and Events 1-7 

1.7 Interprocess Communication 1-8 

1.8 Using the OS Interface 1-8 

1.9 Running Programs under the OS 1-8 

1.10 Writing Programs That Use the OS 1-8 

Chapter 2 

THE FILE SYSTEM 

2.1 File Names 2-3 

2.2 The Working Directory 2-4 

2.3 Devices 2-5 

2.4 Storage Devices 2-5 

2.5 The volume Catalog 2-6 

2.6 Labels 2-6 

2.7 Logical and Physical End Of File 2-6 

2.8 File Access 2-7 

2.9 Pipes 2-8 

2.10 File System Calls 2-9 

Chapter 3 
PROCESSES 

3.1 Process structure 3-4 

3.2 Process Hierarchy 3-4 

3.3 Process Creation 3-5 

3.4 Process Control 3-5 

3.5 Process Scheduling 3-6 

3.6 Process Termination 3-7 

3.7 A Process Handling Example 3-7 

3.8 Process system calls 3-9 



Chapter 4 

MEMORY MANAGEMENT 

4.1 Data Segments 4-3 

4.2 The Logical Data Segment Number, 4-3 

4.3 Shared Data Segments , 4-4 

4.4 Private Data Segments 4-4 

4.5 Code Segments 4-4 

4.6 Swapping.. 4-5 

4.7 Memory Management System Calls. 4-5 

Chapter 5 

EXCEPTIONS AND EVENTS 

5.1 Exceptions,. 5-3 

5.2 System Defined Exceptions 5-4 

5.3 Exception Handlers 5-4 

5.4 Events 5-7 

5.5 Event Channels 5-7 

5.6 The System Clock 5-12 

5.7 Exception Management System Calls 5-12 

5.8 Event Management System Calls 5-18 

5.9 Clock System calls 5-28 

Chapter 6 

CONRGURATION 

6.1 Configuration System calls 6-3 



Appendix A 

CPERATING SYSTEM INTERFACE 

Appendix B 

SYSTEM RESERVED EXCEPTION NAMES 

Appendix C 

SYSTEM RESERVED EVENT TYPES 

Ajrx)6ndlx D 

GPERATING SYSTEM ERROR MESSAGES 

Appendix E 

FS JNFO FIELDS 

INDEX 



T 1 AT3T T?Q 



2-1 Device Control Functions Required Before Using a Device 2-27 

2-2 Device_ContiDl Output Functional Groups 2-28 

2-3 Decode Mneumonics 2-30 

2-4 Device Information 2-32 

2-5 Disk Hard [Error Codes 2-34 



FIGURES 



2-1 Disk Hard Error Codes 2-34 

2-2 The Relationship of COMPACT and TRUNCATE 2-38 

3-1 Process Address Space Layout 3-4 

3-2 Process Tree 3-5 

5-1 Stack at Exception Handler Invocation 5-6 



PREFACE 



The Contents of this Manual; 

mis manual describes tne operating system service calls that are avalbaoie to 
Pascal and assembler programs. It Is written for experienced Pascal 
programmers, and does not explain elementary terms and programming 
techniques. We assume that you have read the Lisa Owner's Guldewti Workshop 
user's Guide for we Lisa and are familiar with your Lisa system. 

Chapter 1 is a general Introduction to the Operating system. 

Chapter 2 describes the File System and the available file system calls. This 
includes a description of the interprocess communication facility, pipes, and the 
Operating System calls that allow processes to use pipes. 

Chapter 3 describes the calls available to control processes, and also describes 
the structure of processes. 

Chapter 4 describes how processes can control their use of available memory. 

Chapter 5 describes the use of events and exceptions to control process 
synchronization. It also describes the use of the system clock. 

Chapter 6 describes the calls you can use to find out information about the 
configuration of tne system. 

Appendix A contains the source text of SYSCALL, the unit that contains the 
type, procedure, and function definitions discussed in this manual. 

Appendix B contains a list of system-defined exception names. 

Appendix c contains a list of system-defined event names. 

Appendix D contains a list of error codes that may be produced by the calls 
documented in this manual. 

Type and syntax conventions 

Bold face type is used in this manual to distinguish programming keywords and 
constructs from English text For example, FLUSH is the name of a system call. 
System call names are also capitalized in this manual, although Pascal does not 
distinguish between lower and upper case characters, itallosare used to indicate 
new terms that are to be explained. 
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INTRODUCTION 

The Operating System (OS) provides an environment in which multiple processes 
can coexist, with the ability to communicate and share data. It provides a file 
system for I/O and information storage, and handles exceptions (software 
Interrupts) and memory management. 

1.1 The Main Functions 

The OS has four main functional areas: the File system, Process Management, 
Memory Management, and event and exception handling. 

The File System provides input and output. The File System accesses devices, 
volumes, and files. Each object, whether a printer, disk file, or any other type of 
object, is referenced by a pathname. Every I/O operation is performed as an 
uninterpreted byte stream. Using the File System, all I/O is device independent. 
The File System also provides device specific control operations. 

A process is an executing program and its associated data, several processes can 
execute concurrently by multiplexing the processor between them. These 
processes can be broken Into segments which are automatically swapped into 
memory as needed. 

Memory managment routines handle data segments. A data segment is a file that 
can be placed in memory and accessed directly. 

Exceptions and events are process communication constructs provided x^ the OS. 
An event is a message sent from one process to another, or from a process to 
itself, that is delivered to the receiving process only when the process asks for 
that event. An exception is a special type of event that forces itself on the 
receiving process. There is a set of system defined exceptions (errors), and 
programs can define their own. system errors such as division by zero are 
examples of system defined exceptions. You can use the system calls provided to 
define any exceptions you want. 

All four of these areas are described further later in this chapter. 

1.2 Using the OS Functions 

Both built in language features and explicit OS system cans can access OS 
routines to perform desired functions. For example, the Pascal writein 
procedure is a built in feature of the language. The code to execute a writein is 
supplied in IOSPASLIB, the pascal run time support routines library. This code is 
added to the program when the program is linked. The code provided calls as File 
System routines to perform the desired output. 
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You can also call OS routines explicitly. This is usually done when the language 
does not provide the operation youi want. OS routines allow Pascal programs, for 
example, to create new processed which could not otherwise be done, since 
Pascal does not have any built in prbcess handling functions. 

All calls to the OS are synchronous, which means they do not return until the 
operation is complete. Each call 'returns an error code to indicate if anything 
went wrong during the operationi Any non zero value indicates an error or 
warning. Negative error codes indicate warnings. 

1.3 The File System 

The File System performs all 1/ti as uninterpreted byte streams. These byte 
streams can go to files on disk or to other devices, such as a printer or an 
alternative console?. In all casesj the device or file has a File System name. 
Except for device control functions, the File System treats devices and files in 
the same way. 

The File System allows sharing of aU types of objects. 

The File System provides for namiifig objects (devices, files, etc.). A name in the 
File System is called a patnname A complete pathname consists of a directory 
name and a file name. The file riame is meaningful only for storage devices 
(devices that store byte streams forjlater use, such as disks). 

Each process has a working directory associated with it. This allows you to 
reference objects with an incomplete pathname. To access an object in tne 
working directory, just give its file name. To access an object in a different 
directory, give its complete pathname. 

Before a device can be accessed, it must be mounted. Devices can be mounted 
using the Preference tool, or by using the MOUNT call (see Chapter 2 of this 
manual). If the device is a storage device, the mount operation makes a volume 
name available. A volume name lsj a logical name for a disk, and is saved on the 
disk itself. The mount operation logically connects the volume to the system, so 
that the files on the volume may be accessed. The volume name can replace a 
device name in a pathname used to access an object on the disk. The volume 
name allows you to access a file with the same pathname no matter where the 
drive Is actually connected. 

If a device is specified in the configuration list (created by the Preference tool) 
and it is physically connected to the! Lisa, then the device can be accessed. There 
are some operations that can be performed on unmounted (unconfigured) devices. 
Two examples are DEVlCEjCONTF^OL calls (see Chapter 2 of this manual) and 
scavanging. Logically mounting a volume on a device makes file access to the 
volume possible. For storage devices, a volume is an actual magnetic medium 
that can contain recorded files. For non-storage devices, volumes and files are 
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concepts used to maintain a uniform interface. Files on non-storage devices 
(such as printers) do not store data, but acts as "ports" for performing I/O to the 
devices. 

The basic operations provided by the File System are as follows: 

mount and unmount - make a volume accessible/inaccessible 
open and close - make an object accessible/Inaccessible 
read and write - transfer information to and from an 

object 
device control functions - control device specific 

functions 

Some operations apply only to storage devices: 

allocate and deallocate - specify size of an object 
manipulate catalog - controls naming of objects and 
creation and destruction of objects 
manipulate attributes - look at or change the 

characteristics of the object 

In addition to the data in an object, the object itself has certain characteristics. 
These are called its attributes They include such Information as the length and 
creation date of a file. Calls are available to access the attributes of any File 
System object, in addition to the system defined attributes, objects on a storage 
device can have a label The label is available for programs to store information 
mat they can Interpret. 

Non-storage devices (such as printers) are accessed with a limited set of 
operations. They must be mounted and opened before they can be accessed. 
Sequential read and/or write operations are available as appropriate for the 
device. Device control functions are available to perform any device specific 
functions needed. The file name portion of the complete pathname for a 
non-storage device is not used by the File System, although you do have to 
provide one when you open the device. 

For storage devices, the same sequential read and write operations are valid as 
for non-storage devices. Storage devices also must be mounted, and particular 
files opened, before the files can be used. They have appropriate device control 
functions available. 

When writing to a disk file, space for the file is allocated as needed, space for a 
file does not need to be contiguous, and in some cases this automatic allocation 
can result in a fragmented file, which may slow file access. To insure rapid 
access, you can pre-aiiocate space for the file. Pre-aiiocatlng the file also 
ensures that the process will not run out of space on the disk. 

Four types of objects can be stored on storage devices. These are files, pipes, 
data segments, and event channels. Files, already discussed, are simply arrays of 
stored data Pipes are objects provided for inter-process communication. Data 
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segments are special cases of files that are loaded into memory along with 
program code. Event channels are!pipes with a specialized structure imposed by 
the system. 

:L4 Process Management 

A process is an executing program ;and its associated data. Several processes can 
exist at one time, and they appear to run simultaneously because the CPU is 
multiplexed among them. The scheduler decides what process should use the 
CPU at any one time. It uses a generally non-preemptive scheduling algorithm. 
This means that a process will not 10se the CPU unless it blocks. 

A process can lose the CPU when oriie of the following happens: 

o The process calls an Operating System procedure 
or function 

o The process references one of its code segments 
that is not currently in memory 

If neither of these occur, the process will not lose the CPU. 

Every process is started by another process. The newly started process is called 
the son process The process thai started it is called its fatner process The 
resulting structure is a tree of processes (See Figure 3-2). 

When any process terminates, all its son processes (and their descendants) are 
also terminated. 

When the OS is booted. It starts a shell process. The shell process then starts any 
other processes desired by the user. | 

Every newly created process hasi the same system-standard attributes and 
capabilities. These can be changed by using system calls. 

Any processes can suspend, activate, or kill any other process for which the 
global ID is known, as long as the other process does not protect itself. 

The memory accesses of an executing process are restricted to its own memory 
address space. Processes can comrrjunicate with other processes by using shared 
files, pipes, event channels, or shared data segments. 

A process can be in one of three states: ready, running, or blocked. A ready 
process is waiting for the scheduler to select It to run. A n/nnln&process is 
currently using the CPU to execute its code. A dlockedprocess is waiting for 
some event, such as the completion! of an I/O operation. It will not be scheduled 
until the event occurs, at which point it becomes ready. A terminated process 
has finished executing. 

Each process has a priority from l to 255. The higher the number, the higher the 
priority of the process. Priorities 226 to 255 are reserved for system processes. 
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The scheduler always runs the ready process with the highest priority. A process 
can change its own priority, or the priority of any other process, while it is 
executing. 

15 Memory Management 

Memory managment is concerned with what is in physical memory at any one 
time. Each process can use up to 128 segments. Each segment can contain up to 
128 Kbytes. These segments are of two types: code segments and data segments. 
The total amount of memory used Dy any one process can exceed the available 
RAM of the Lisa. The Operating System will swap code segments in and out of 
memory as they are needed. To aid the Operating System in swapping data 
segments, calls are provided to give programs the ability to define which data 
segments must be in memory while a particular part of the program is executing. 

You have control of how your program is divided up. For executable code 
segments, you use the segmentation commands of the Pascal compiler to break 
the program in pieces. 

In addition to residing in memory, data segments can be stored permanantly on 
disk. They can be accessed with calls similar to File System calls. This allows 
you to use a data segment as a direct access file — a file that is accessed as part 
of your memory space. 

Calls are provided for making, killing, opening, and closing data segments. You 
can also change the size of a data segment and set its access mode to read only or 
read write. In addition, you can make a permanent disk copy of the contents of a 
data segment at any time. Other calls give you ability to force the contents of 
the data segment to be swapped into main memory, so they can be accessed by 
your process. 

1.6 Exceptions and Events 

An exception is an unexpected condition in the execution of a process (an 
interrupt). An event is a message from another process. 

An exception can be generated by either the system or an executing program. 
System exceptions are generated by various sorts of errors such as divide by zero, 
illegal instruction, or illegal address. System exception handlers are supplied 
that terminate the process. You can write your own exception handlers for any 
of these exceptions if you want to try to recover from trie error. 

User exceptions can be declared, and exception handlers written to process 
them. Your program can then signal this new exception. 

Events are messages sent from one process to another. They are sent through 
event channels. 
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A process that wants to receive a njiessage from an event channel executes a call 
to wait for an event on that channel. This will give it the next message, if one 
exists, or block the process until a message arrives. 

If a process wants to know when an pvent arrives, but does not want to wait for it, 
it can use a call event channel. This is set up by associating a user exception with 
the event channel when it is opened. The Operating System will then invoke the 
corresponding user exception handier whenever a message arrives in the event 
channel. 

1.7 interprocess Communication 

There are four methods for interprocess communication. These are: shared files, 
pipes, event channels, and shared da^a segments. 

Shared files are used for high volume transfers of information. It is necessary to 
coordinate the processes somehow to prevent them from overwriting each 
other's information. 

Pipes are used for communication bbtween processes with an uninterpreted byte 
stream. The pipe mechanism provides for the needed synchronization because a 
process will block if it is trying to r$ad from an empty pipe or write to a full one. 
A read from a pipe consumes the information, so it is no longer available. Only 
one process can read from a given pijDe. 

Event channels are similar to pipjes, except they transmit short, structured 
messages instead of uninterpreted bytes. 

A shared data segment can be used to transmit a large amount of data rapidly. 
Having a shared data segment means that this data segment is in the memory 
address space of all the processes that want to use it. All the processes can then 
directly read and write information in the data segment It is necessary to 
provide some sort of synchronization to keep one process from overwriting 
another's information. 

1.8 Using the OS Interface 

The interface to all the system calls is provided in the unit SYSCALL. This unit 
can be used to provide access to thejcalls. See the worksnop user's Guide for tne 
Lisa for more Information on using SYSCALL. 

1.9 Running Programs Under the OS 

Programs can be written and run by qsing the Workshop. 

1.10 Writing Programs That Use the os I 

You can write a program that calls 0$ routines to perform needed functions. This 
program USES the unit SYSCALL, then calls the routines needed. 
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THE FILE SYSTEM 

The File system provides device independent, i/o, storage with access protection, 
and uniform file naming conventions. 

Device independence means that all I/O is performed in the same way, whether 
the ultimate destination (or source) Is disk storage, another program, a printer, or 
anything else. In all cases, I/O Is performed to or from files, although those files 
are often also devices, data segments, or programs. 

Every file is an uninterpreted stream of eight-olt bytes. 

A file that is stored on a block structured device, such as a disk, is listed in a 
cataiog{a\$o called a directory and has a name. For each such file the catalog 
contains an entry describing the file's attributes, including the length of the file, 
its position on the disk, and the last backup copy date. Arbitrary 
application-defined information can be stored in an area called the file label 
Each file has two associated measures of length, the Logical Eno 'of 'File (LEOF) 
and the Physical End of File (PEOF) The LEOF is a pointer to the last byte that 
has meaningful data. The PEOF is a count of the number of blocks allocated to 
the file. The pointer to the next byte to be read or written is called the file 
marker. 

since I/O is device Independent, application programs do not have to take 
account of the physical characteristics of a device. When the I/O is to or from a 
disk, or any other block structured device, programs can make I/O requests in 
whole-block increments, which improves program performance. 

ah input ano output is synchronous in that the I/O requested is performed before 
the call returns. The actual I/O, however, is asynchronous, in that processes may 
block when performing i/o. (see section 3.5, Process scheduling, for more 
information on blocking.) 

To reduce the impact of an error, the file system maintains distributed, 
redundant information about the files on storage devices. Duplicate copies of 
critical Information are stored in different forms and in different places on the 
media. All the files are able to identify and describe themselves, and there are 
usually several ways to recover lost information. The scavenger utility is able to 
reconstruct damaged catalogs from the information stored with each file. 

2.1 File Names 

ah the files known to the Operating system at a particular time are organized 
into catalogs. Each disk volume has a catalog that lists all the files on the disk. 
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Any object catalogued In the file system can De named by specifying the volume 
on which the file resides and the; file name. The names are separated by the 
character "-". Because the top catalog In the system has no name, all complete 
pathnames begin with "-". 

For example, 

-Lisa-format. text narces! a file on a voiune narked LISA. 

The file name can contain up to 32j characters, if a longer name is specified, the 
name is truncated to 32 characters. Accesses to sequential devices use an 
arbitrary dummy filename that is ignored but must be present in the pathname. 
For example, the serial port pathname 

-RS232B 

is insufficient, but 

-RS232B-XYZ 

is accepted, even though the -XYZlportion is ignored. Certain device names are 
predefined: 

RS232A serial Port A 

RS232B serial Port t 

PARAPORT Parallel Poijt 

SLOTxCHANy serial ports, where x Is 1, 2, or 3 and y is l or 2 

MAINCONSOLE writeln and f eadln device 

altconsole writeln and reaam device 

UPPER upper Diskette drive (Drive l) 

lower Lower Diskette drive (Drive 2) 

BITBKT Bit bucket: dajta is thrown away when directed here 

See Chapter 6, Configuration for m0re information on device names. 

Upper and lower case are not significant in pathnames: 'TESTVOL' is the same 
object as TestVol'. Any ASCII character is legal in a pathname, including the 
non-printing characters and blank spaces. (However, use of ascii 13, a 
return, in a pathname is strongly discouraged.) 

2.2 The working Directory 

It is sometimes inconvenient to specify a complete pathname, especially when 
working with a group of files in the|same volume. To alleviate this problem, the 
operating system maintains the name of a working directory for each process. 
When a pathname is specified without a leading "-", the name refers to an object 
in the working directory. For example, if the working directory is -LISA the 
name FORMAT.TEXT refers to the same file as -LISA-FORMAT.TEXT. The 
default working directory name is trie name of the boot volume directory. 

You can find out what the working directory is with GET_WORKING_DIR. You 
can change to a new working directory with ^t_workingjdir. 
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23 Devices 

Device names follow the same convention:? as other file names. Attributes like 
baud rate are controlled by using the DEVICE_(X)NTROL call with the 
appropriate pathname. 

Each device has a permanently assigned priority. From highest to lowest the 
priorities are: 

Power on/off button 

Serial Port A (RS232A) 

serial Port b (RS232B, tne leftnost port) 

I/O Slot i 

I/O Slot 2 

I/O Slot 3 

Keyboard, muse, battery powered clock 

10 m systen tiner 

CRT vertical retrace interrupt 

Parallel Port 

Diskette l (upper) 

Diskette 2 (LOWER) 

video screen 

The device driver associated with a device contains information about the 
device's physical characteristics such as sector size and Interleave factors for 
disks. 

2.4 Storage Devices 

on storage devices, sucn as disk drives, tne File system reads or writes file data in 
terms of pages. A page is the same size as a block. Any access to data in a file 
ultimately translates into one or more page accesses. When a program requests 
an amount of data that does not fit evenly into some number of pages, the File 
System reads the next highest number of whole pages. Similarly, data is actually 
written to a file only in whole page increments. 

A file does not need to occupy contiguous pages. The File System keeps track of 
the locations of all the pages that make up a file. 

Each page on a storage device is self-identifying, and the page descriptor is 
stored with the page contents to reduce the destructive impact of an I/O error. 
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The eight components of the page descriptor are: 

version number 
voiune identifier 
File identifier 
Amount of data on the page 
Page name 

page position In tne file 
Forward link 
Backward link 

Each volume has a Medium Descriptor Data File (MDDF) which describes the 
various attributes of the medium such as its size, page length, block layout, and 
the size of the boot area. The MDDF is created when the volume is initialized. 

The File System also maintains a record of which pages on the medium are 
currently allocated, and a catalrig of all the files on the volume. Each file 
contains a set of file hints, which del scribe and point to the actual file data. 

2.5 The Volume Catalog 

On a storage device, the volume catalog provides access to the files. The catalog 
is itself a file that maps user namds into the internal file identifiers used by the 
Operating System. Each catalog entry contains a variety of information about 
each file including: 

name 

type 

internal file number and address 

size 

date and tine created, last modlf led, and last accessed 

file identifier 

safety switch 

The safety switch is used to avoid accidental deletions. While the safety switch 
is on, the file cannot be deleted.! The other fields are described under the 
lookup file systemi call. 

The catalog can be located anywhere on the medium. 

2.6 Labels 

An application can store its own information about a file in an area called the 
file laoel The label allows an application to keep the file data separate from 
information maintained about the file. Labels can be used for any object in the 
file system. The maximum label Islze is 128 bytes. I/O to labels is handled 
separately from file data I/O. 

2.7 Logical and Physical End of File 

A file contains some number of bytes of data recorded In some number of 
physical pages. Additional pages might be allocated to the file, which do not 
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contain any file data. There are, therefore, two measures of the end of the file 
called the logical and physical end of file,, The Logical End of File (LEOF) is a 
pointer to the last stored Dyte that has meaning to the application. The Physical 
End of File (PEQF) is a count of the number of pages allocated to the file. 

In addition, each open file has a pointer associated with it, called the file marker, 
that points to the next byte in the file to be read or written. When the file is 
opened, the file marker points to the first byte (byte number 0). The file marker 
can be positioned implicitly or explicitly using the read and write calls. For 
example, when a program writes to a file opened with Append access, the file 
marker is automatically positioned to the end of the file before new data is 
written. The file marker cannot be positioned past LECF, except by a write 
operation that appends data to a file. 

When a file is created, an entry for it is made in the catalog specified in its 
pathname, out no space is allocated for the file itself. When the file is opened by 
a process, space can be allocated explicitly by the process, or automatically by 
the Operating System. If a write operation causes the file marker to be 
positioned past the LEOF marker, LECF, and PEOF, if necessary, are 
automatically extended. The new space is contiguous if possible. 

2.8 File Access 

The File System provides a device Independent byte stream interface. As far as 
an applications program is concerned, a specified number of bytes is transferred 
either relative to the file marker or at a specified byte location in the file. The 
physical attributes of the device or file are not important to the application, 
except that devices that do not support positioning can only perform sequential 
operations, and programs can Improve performance somewhat by taking 
advantage of a device's physical characteristics. 

Programs can request any amount of data from a file. The actual i/o, however, Is 
performed in whole-page increments, when devices are block structured. 
Therefore, programs can optimize I/O with such devices by setting the file 
marker on a page boundary and making I/O requests in whole-page increments. 

A file can be open for access simultaneously by more than one process. All 
requests to write to the file are completed before any other access to the file is 
permitted. When one process writes to a file the effect of that write operation is 
immediately available to all other processes reading the file. The other 
processes may, however, have accessed the file in an earlier state. Data already 
obtained by a program are not changed. The programmer must insure that 
processes maintain a consistent view of a shared file. 

When you open a file, you specify the kind of access allowed on the file. When the 
file is opened, the Operating System allocates a file marker for the calling 
process ana a run-time identification number caned tne remum The process 
must use the refnum in subsequent calls to refer to trie file. Each operation using 
the refnum affects only the file marker associated with that refnurn. 
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Processes can snare the same file rnarker. In this access mode (global, refnurn) 
each process uses the same refnum for the file. When a process opens a file in 
giooai access mode, the refnum it gets back can he passed to any other process, 
and used by any process. Note that any number of processes can open a file with 
global, refnum, but each time the OPEN call is used a different refnum is 
produced. Each of those refnumsi can be passed to other processes, and each 
process using a particular refum 1 shares the same file marker with other 
processes with the same refum. processes using different refnums, however, 
always nave different file markers, whether or not those refurns were obtained 
with globaljrefnunm. 

A file can also be opened in private mode, which specifies that no other OPEN 
calls are to be allowed for that filei A file can be opened with giobaljrefnum and 
private, which opens the file for global access, but allows no other process to 
open that file. By using this call,! processes can control which other processes 
have access to a file. The opening process passes the global refnum to any other 
process that is to have access, and the system prevents other processes from 
opening the file. 

Programmers should be aware that processes using global access may not be able 
to make any assumptions about the location of the file marker from one access to 
the next. 

2.9 Pipes 

Because the Operating System supports multiple processes, a mechanism is 
provided for interprocess communication. This mechanism is called a plpa 
Pipes are very similar to the other jobjects in the file system — they are named 
according to the sanne rules, and they can have labels. 

As with a file, a pipe is a byte stiream. With a pipe, however, information is 
queued In a f lrst-ln-f lrst-out manner. Also, a pipe can nave only one reader at a 
time, and once data is read from a pipe it is removed from the pipe. 

A pipe can only be accessed in sequential mode. Although only one process can 
read data from a pipe, any number jof processes can write data into it. Because 
the data read from the pipe is consumed, the file marker is always at zero. If the 
pipe is empty and no processes have it open for writing, EOF (End Of File) is 
returned to the reading process. If £ny process does have it open for writing, the 
reading process Is suspended until enough data to satisfy the call arrives in the 
pipe, or until all writers close the pljjje. 

When a pipe is created, Its sl2e is o bytes, unlike with ordinary flies, the 
initializing program must allocate space to the pipe before trying to write data 
into it. to avoid deadlocks between tne reading process and the writers, trie 
operating system does not allow a! process to read or write an amount of data 
greater than half the physical size of the pipe. For this reason, you should 
allocate to the pipe twice as much space as the largest amount of data in any 
planned read or write operation. 
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A pipe is actually a circular buffer with a read pointer and a write pointer. All 
writers access the pipe through the same write pointer. Whenever either pointer 
reaches the 'end* of the pipe, it wraps hack around to the first oyte. if the read 
pointer catches up with the write pointer, the reading process blocks until data 
are written or until all the writers close the pipe. Similarly, if the write pointer 
catches up with the read pointer, a writing process blocks until the pipe reader 
frees up some space or until the reader clones the pipe. Because pipes have this 
structure, there are certain restrictions on some operations when dealing with a 
pipe. These restrictions are discussed with the relevant file system calls. 

Processes can never make read or write requests bigger than half the size of the 
pipe because that the Operating System always fully satisfies each read or write 
request before returning to the program, in other words, if a process asks for 100 
bytes of data from a pipe, the Operating System waits until there are 100 bytes of 
data in the pipe, and then completes the call. Similarly, if a process tries to write 
100 bytes of data into a pipe, the Operating System waits until there is room for 
the full 100 bytes before writing anything into the pipe. If processes were 
allowed to make write or read requests for greater than half of a particular pipe, 
it would be possible for a reader and a writer to deadlock, with neither having 
room in the pipe to satisfy its requests. 

z.io File system calls 

This section describes all the Operating System calls that pertain to the file 
system, a summary of all the operating system cans can oe found in Appendix a. 
The following special types are used in the file system calls.- 

Pathname = STRING [Max_Pathnane]; (* flax_Pathnane = 255 *) 
Ejteme = STRING [nax_Ename ]; (* flax_ENane = 32 *) 
Accesses = (DRead, DWrite, Append, Private, Global_ref nun); 
nset = set OF Accesses; 
ionode = (Absolute, Relative, sequential ),- 

The fsjnf o record and its associated types are described under the lookup call. 
The Dctype record is described under the DEVICE CONTROL call. 
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riAKE_FlLE (VarEcoderlnteger; I 
Var Path: Pathname; 
LaDei__size: integer) 

mKE_piPE ( var Ecoae : integer; j 
Var Path : Pathname; 
LaDei._size rinteger ) 

Ecoae : Error indication 

Path: Nane of n6w object 

Label_size: Number of j bytes for the object's label 

MAKE_F1LE and make_pipe create the specified type of object with the given 
name. If the pathname does not specify a directory name (more specifically, if 
the pathanme does not begin wiith a dash), the working directory is used. 
Label_size specifies the initial size in bytes of the label that the application 
wants to maintain for the object. It must be less than or equal to 128 bytes. The 
label can grow to contain up to 1^8 bytes no matter what its initial size. Any 
error indication is returned in Ecod£. 

The example below checks to se|e whether the specified file exists before 
opening it. 

CONST FlleExiStS = 890; 
VAR FileRef Num, ErrorCode : INTEGER; 
FlieNaiPierPathNane; \ 
Happy -.BOOLEAN; 
Response: CHAR; 
BEGIN 

Happy :=F ALSE; 
WHILE NOT Happy DO 
BEGIN 

REPEAT i (* get a file name*) 

WRITE(* Filename: *); 
READLN(FileName); 
UNTIL LENGTH(FlleNamei)>0; 

nAKE_FILE(ErrorCode,FileName;o); (*no label for this file*) 
if (Errorcoaeoo) then (* does file already exist? *) 

IF (ErrorCode=FlleExlsts) THEN (* yes *) 

BEGIN 

WRITE (FileName, ' already exists, overwrite? '); 
READLN(Response); 

Happy ::=(Response IN [•yVY*]); (*go ahead and 

overwrite*) 

END 
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ELSE URITELN( ' Error ' , ErrorCode, ' while creating file . ' ) 

ELSE Happy :=TRUE; 
END; 

OPEN(Errorcoae, FlieName, FlieRef Num, [Dwrlte]); 
END; 
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KILLJBJECT (Var Ecode: Integer j 
var Path: Pathname); 

Ecode: Error indicator 

Path: Nane of object to be deleted 

KILLJBJECT deletes the object giyen in Path from the file system. Objects with 
the safety switch on cannot be deleted, if a file or pipe is open at the time of the 
KILLJBJECT call, its actual deletion is postponed until it has been closed by all 
processes that have it open. During this period no new processes are allowed to 
open it. The object to be deleted need not be open at the time of the 
KILLJBJECT call. A KILLJBJECT call can be reversed by unkill_file, as 
long as the object is a file and is still open. 

The following program fragment deletes files until carriage return is typed: 

CONST FlleNOtFOUnd=894; 
VAR FileNane : PathNawe; 
Errorcode : integers- 
begin 

REPEAT 

WRITECFile to delete: '); 
READLN(FileNane); 
IF (FileNaneO") THEN 
BEGIN 

KlLL_OBJECT(Errorcock FlleNane); 
if (Errorcodeoo) tHen 
IF (ErrorCode=FileNotFound) THEN 
yRlTELN(FlieNane, * ! not found.') 

ELSE URITELNC Error ',ErrorCode, ' while deleting file.') 
ELSE URlTELN(FiieNaine, ' deleted.*); 
EM) 
until (FlieName="); 
END; 
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UNKILL_FILE ( Var Ecode : integer; 

Refnun: integer; 
var New_nane:e__nane) 

Ecode: Error indicator 

Refnifi: Refnun of the killed and open file 

New_nane:New nane for the file being restored 

UNKILL_FILE reverses the effect of KILL JBJECT, as long as the Killed object 
Is a file that Is still open, a new catalog entry Is created for the file with the 
name given in New_name. New_name is not a full pathname: the resurrected file 
remains in the same directory. 
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RENAMEJENTRY (Var Ecode: Integer; 
Var Path: Pathname; 
Var Neuname:E_Name) 

Ecode: Error indicator 
Path: Ob ject ' s old: name 
Neuname : Object ' s neu! nane 

RENAME_ENTRY changes the name of an object in the file system. Newname 
can not be a full pathname. The name of the object is changed,, but the object 
remains in the same directory. The following program fragment changes the file 
name Of FORMATTER.LIST to NEWFORMAT.TEXT. 

VflR DlOName : Pathname; 

NewName:E_Name; 

Errorcode: INTEGER 
BEGIN 

OldNare : = ' -LISA-FORflMTER .LIST * ; 

NewName : = * NEWFORHATi. TEXT ' • 

RENAnEjENTRY(Errorcbcte, oiONane, NewName); 

END; 

The file's new full pathname is '-lisa-newformat.text'. 

volume names can be renamed by specifying only the volume name in Path. Here 
is a sample program fragment which changes a volume name. Note that trie 
leading dash (-), given in Oldname, Is not given in Newname. 

VAR 01dName:PathName; 

NewName :E_Name; 

Errorcode: INTEGER 
BEGIN 

Oldname : = ' -thomas " ; 

Newname : = ' steams ' ; 

RENArE_ENTRY(Errorcdde^ Oldname, Newname); 
END; 
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LOOKUP (Var Ecode : Integer; 
var Path :Patnnarce; 
Var Attributes :Fs_Info) 

Ecode: Error indicator 

Path: Object to lookup 

Attributes: Information returned about path 

LOOKUP returns information about an object in the file system. For devices and 
mounted volumes, call lookup with a pathname that names the device or 
volume without a file name component: 

DevNane:=" -UPPER'; (* Diskette drive l *) 

LOOKUP(ErrorCode, devname, infoRec); 

If the device is currently mounted and is block structured, the record fields of 
Attributes contain meaningful values; otherwise, some values are undefined. 

The fs_info record is defined as follows. The meanings of the information fields 
are given in Appendix E. 

f s_inf O = RECORD 

nane: e_nane; 
ctevnum: INTEKR; 
CASE OType : inf o_type OF 

devlce_t, voiume_t: 

(iochannel: INTEGER 

devt: devtype; 

SlOt_no: INTEGER; 

fS_Size: LONGINT; 

VOl_size: LONGINT; 

biockstructurea, 
mounted: BOOLEAN; 
opencount: longint; 
privatedev, 
renote, 

lOCkeddev: BOOLEAN; 

nount_penaing, 

unrount_pending: BOOLEAN; 

voinane, 

password: e_nane; 

fsverslon, 

vol id, 

VOlnun: INTEGER; 
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blocksize, 
datasize, 
clustersizp, 

fllecount:! INTEGER; (*Numoer of files on vol**) 
freecount:! L0NGINT; (*Number of free blocks *) 
DTVC, ! (* Date volume Created *) 
DTVB, (* Date Volume last Backed up *) 
DTVS:LONGlNT;(* Date volume last scavanged *) 
flachine_id^ 
overmount stamp, 
raster jcop^_id: LONGINT; 
privileged^ 

write jprotected: BOOLEAN; 
master, 
copy, 

scavenge_ftLag: BOOLEAN); 
object_t: ( 

size: LONGINT; (*actual no of bytes written*) 
psize: LONGINT; (*pbysical size in bytes*) 
lpslze: iNtTEGER; (*Loglcai page size In bytes*) 
ftype: filetype; 
etype: entry type; 

DTC, 
DTA, 

Dm, 

DtB: LONGINT; 

refnum: INTEGER; 

fmark: LONGINT; 

acmode: mset; 

nreaders, (* Number of readers *) 

nwriters, (* Number of writers *) 

nusers: integer; (* Number of users *) 

fuid: uid; (* unique identifier *) 

eof, (* EOF encountered? *) 

safety_on, i (* safety switch setting 



* Date Created *) 

* Date last Accessed *) 

* Date last Mounted *) 
(*Date last Backed up *) 



(* file marker 
(* access mode 



END; 



kswltcn: boolean; (* nas file been killed? 
private, (*; File opened for private access? 
locked, (*!is file locked? *) 
protected :toLEAN);(* File copy protected? 



*) 

*) 
*) 

*) 



Uld = INTEGER; 

Inf o_Type = (device_t, volume_t, obJect_t); 

Devtype = (diskdev, pascalbd, seqdev, bitbkt, non_io); 
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Filetype = (undefined, MDDFFlle, rootcat, freelist, 
badblocks, sysdata, spool, exec, usercat, 
pipe, oootf lie, swapaata, suapcoae, ranap, 
userfile, killedobject); 

Entrytype = (enptyentry, catentry, llrikentry, flieentry, 
pipeentry, ecentry, kllledentry); 

The EOF field of the fsjnfo record is set after an attempt to read more bytes 
than are available from the file marker to the logical end of the file, or after an 
attempt to write when no disk, space is available, if the file marker is at the 
twentieth byte of a twenty-five byte file, for example, you can read up to 5 
bytes without setting EOF, but if you try to read 6 bytes, the file system gives you 
only 5 bytes of data, and EOF is set. 

The following program reports how many bytes of data a given file has: 

VAR InfoRec:Fs_Info;(**info3rnation returned by LOOKUP and 

INFO*) 
FileNane :PathNane; 
ErrorCode: INTEGER- 
BEGIN 
URITE('File: '); 
READLN(FileNane); 

L00KUP(ErrorCode, FileNane, Inf oRec); 
IF (ErrorCodeOO) THEN 

URITELNC cannot lookup \ FileNane) 
ELSE 
(JRITELN(FileNane, ' has ', Inf oRec. Size, * bytes of data/); 
END; 
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INFO (var Ecode : integer; 
Refnum: integer; 
Var Reflnfo:Fs_lnfo) 

Ecode : Error indicator 

Refnun: Reference | nunber of object in file system 

Refinfo: Information returned about refnun* s object 

INFO serves a function similar to! that of LOOKUP, but is applicable only to 
objects in the file system which are open. The definition of the Fsjnfo record is 
given under LOOKUP and in Appendix A. 
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SET_FILE_INFO ( Var Ecocte : Integer; 

Ref nun : integer; 
Fsi:Fs_Info) 

Ecode: Error indicator 

Refnun: Reference nurtier of object in file systert 

Fsi: New information about the object 

SET_FILE_INFO changes the status information associated with the given object. 
This call works in exactly the opposite way that LOOKUP and INFO work, in that 
the status information is given by your program to SET_FILE_INFO. The fsi 
argument is the same type of information record as that returned by LOOKUP and 
INFO. The object must be open at the time this call is made. 

The following fields of the information report may be changed: 

o fiie_scavanged 

o file_closedby_OS 

o file_left_open 

o user_type 

o user_subtype 
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OPEN (Var Ecode : integer; 
Var Path :Pathnaine; 
var Ref nun : integer; 
rianip:riset) 

Ecode: Error indicator 

Path: Nane of objject to be opened 

Refnurn: Reference number for object 

fianip: Set of access types 

The OPEN call opens an object so that it can be read or written to. When you call 
OPEN, you specify the set of accesses that will be allowed on that file or 
sequential device. The available acpess types are: 

o Dread — Allows you to reacj any of the file 

o Durite — Allows you to write anywhere in the file (replaces 
existing data) 

o Append — Allows you to add on to the end of the file 

o Private — Prevents other processes from opening tne file 

o Global_refnurc — Creates a refnun that can be passed to other 
processes 

Note that you can give any number of these modes simultaneously. If you give 
dwrite and append in the same CPEN call, dwrite access will be used, see section 
2.8 for more information on giobaijt emum and private access modes. 

if the object opened already exists jand the process calls WRITEJDATA without 
having specified append access, the object can be overwritten. The Operating 
System does not create a temporary file and wait for the CLOSEJBJECT call 
before deciding what to do with the bid file. 

An object can be opened by two separate processes (or more tnan once by a single 
process) simultaneously. If the processes write to the file without using a global 
refnurn, they must coordinate theirlfile accesses so as to avoid overwriting each 
other's data 

Pipes cannot be opened for dwrite access. You must use append if you want to 
write into the pipe. 
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CL0SE_08JECT (Var Ecode: Integer; 
Refnun: integer) 

Ecode: Error indicator 

Refnun: Reference number of object to be closed. 

If refnum is not global, CLOSEJDBJECT terminates any use of Refnum for I/O 
operations. A flush operation is performed automatically ana tne file is saved 
in its current state. If Refnum is a global refnum, and other processes have the 
file open, Refnum remains valid for these processes, and other processes can still 
access the file using Refnum. 

The following program fragment opens a file, reads 512 bytes from it, then closes 
the file. 

TYPE Byte=-128.. 127; 
VAR FlieNane:PathNane; 

ErrorCode, FileRefNun : Integer; 
ActuaiBytes : Longint; 
Buf f er: ARRAY [0.. 511] OF Byte; 
BEGIN 
OPEN(ErrorCode, FileNane, FileRef Nun, [DRead]); 
if (Errorcooe>o) ttcn 

WRITELNC Cannot open ' y FileName) 
ELSE 
BEGIN 

READ_DATA(Errorcoae, 
FileRefNum, 
0RD4(@8uffer), 

512, 

ActuaiBytes, 
Sequential, 

0); 
IF (AetualBytes<512) THEN 
URlTE('Oniy read ', ActuaiBytes, ' bytes fron 
•,FileNane); 
CL0SE_08JECT(ErrorCode, FileRef Nun); 
END; 
END; 
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READJDATA (Var Ecode : Integer; 
Refnun: integer) 
Data_Addr : Longint; 
count -.Longlnt; 
Var Actual: Longlnt; 
riode:loh*ode; 
Offset: Longlnt); 

WRITE JDhTA (var Ecode: Integer) 
Refnunrintegeh 
Data_Addr :Longint; 
Count: Longlnt; 
Var Actual : Longlnt; 
noderionode; 
Offset: Longlnt); 

Ecode: Error indicator 

Refnun: Reference rhunber of object for I/O 

Data_Addr: Address of data (source or destination) 

count: Number of bytes of data to be transferred 

Actual: Actual number of bytes transferred 

node: i/o nooe 

Offset: Offset (absolute or relative Nodes) 

READjDATA reads information from the device, pipe, or file specified by 
Refnum, and writejdata writes Information to it Data_Addr is the address 
for the destination or source of Count bytes of data. The actual number of bytes 
transferred Is returned in Actual. 

Mode can be absolute, relative, or sequential. In absolute mode, offset specifies 
an absolute byte of the file. In relative mode, it specifies a byte relative to the 
file marker. In sequential mode, the offset is ignored (it is assumed to be zero) 
and transfers occur relative to the file marker. Sequential mode (which is a 
special case of relative mode) is the only allowed access mode for reading or 
writing data in pipes or sequential (non-disk) devices. Non-sequential modes are 
valid only on devices that support positioning. The first byte is numbered 0. 

If a process attempts to write data fast the physical end of file on a disk file, the 
Operating system automatically allocates enough additional space to contain tne 
data. This new space, may not be contiguous with the previous blocks, you can 
use the allocate can to Insure tnat any newiy allocated blocks are located 
next to each other, although that will not insure that they are located near the 
rest of tne file. 



2-22 



Operating System Reference Manual for the Lisa The File System 



READ_DATA from a pipe that does not contain enough data to satisfy count 
suspends the calling process until the data arrives in the pipe if any other process 
has that pipe open for writing, if there are no writers, the end of' file indication 
(error 846) is returned by Ecode. Because pipes are circular, WRITEJDATA to a 
pipe with insufficient room suspends the calling process (the writer) until enough 
space is available (until the reader has consumed enough data), if there is a 
reader. If no process has the pipe open for reading and there is not enough space 
in the pipe, the end of file indication (848) is returned in Ecode, 

b£HE 

READ_DATA from the MAINCONSCLE or ALTCONSOLE devices must 
specify count- 1. 



The following program copies a file. Note that you must supply the correct 
location for Syscall in the second line of the program. 

PROGRAM COpyFlle; 

USES (*Syscall. Ob j*) SysCall; 

TYPEByte=-128..127; 

VAR 01dFile,NewFile:PathNane; 

OldRef Nun, NewRef Nun : INTEGER; 

BytesRead, BytesWritten :LONGINT; 

Errorcode : INTEGER; 

Response : CHAR; 

Buffer: ARRAY [0. .511] OF Byte; 
BEGIN 
URITE('Flle to COpy: '); 
READLN(OldFlle); 

OPEN(Errorcode, oidFiie, OldRefNun, [DRead]); 
IF (Errorcode>o) THEN 

BEGIN 

URITELN( f Error ', Errorcode, ' while opening ',01dFile); 

EXlT(copyFlle); 
END; 
URlTE('New file nane: *); 

READLN(NewFlle); 

nAKE_FiLE(Errorcooe,NeuFlie, 0); 
0PEN(ErrorCode, NewFile, NewRef Nun, [DUrite]); 
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REPEAT 
READ_DATA( ErrorCOdej, 

oidRefNum,! 

0RD4(@BUffrer), 

512, BytesRead, Sequential, 0); 
IF (Erroreode=0) AND; (BytesRead>0) THEN 
WRITE .DATA (Errorcode, 
NewRefNun, 
0RD4(@Buffer) y 

BytesRead, Bytesuritten, sequential, 0); 
UNTIL (BytesRead=0) Of^ (Byteswritten=0) OR 
(Errorcode>0); 
IF (Erro]rcode>0) then! 

URITELNl("File copy encountered error *,ErrorCode); 
CL0SE_0BJECT(ErrorCode, NewRef Nun); 
CLOSEjoaiECTCErrorCode 1 , OldRef Nun); 
END. 
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READJLABEL (Var Ecode : integer; 
Var Patn: Pathname; 

Data_Addr : Longint; 

Count: Longint; 
Var Actual -.Longint) 

URITE_LABEL (Var Ecode : Integer; 
varPatn:Patnnane; 

Data_Addr : Longint; 

count: Longint; 
Var Actual : Longint) 

Ecode: Error indicator 

Path: Name of ooject containing tne label 

Data_addr: Source or destination of I/O 

count: Number of bytes to transfer 

Actual: Actual number of bytes transferred 

These calls read or write the label of an object in the file system. I/O always 
starts at tne beginning of the label, count Is tne number of bytes tne process 
wants transferred to or from Data_addr, and Actual is the actual number of bytes 
transferred. An error Is returned If you attempt to read more than the maximum 
label si2e. A label can never be longer than 128 bytes., so you can never read or 
write more than that. 
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DEVICE_C0NTR0L ( Var Ecode : Integer; 
var Path: pathname; 
VsirCPam: dctype) 

Ecode: Error indicator- 
Path: Device to be controlled 
CParn: A record of information for the device driver 

DEVICE_C0NTR0L is used to send device-specific information to a device 
driver, or to ootain device-specif icllnf ormatlon from a device driver. 

Regardless of whether you are setting device control parameters or requesting 
information, you always use a record of type dctype. The structure of dctype is: 

Dctype= RECORD 

dcVersion: INTEGER; 

decode: INTEGER; 

dcData : ARRAY [ . . 9 ] OF LONGINT 

END; 

deversion: always 2 for the functions discussed in this 

document 
decode : control code for device driver 
dcData : specific control or data parameters 

DEVICE_CONTROL functions that set attributes for a device driver are covered 
first 

CONTROLLING DEVICES 

Before you use a device, you should use DEVICE _CONTROL in order to set the 
device driver so that it properly handles the device. Once you begin using the 
device, you are free to call DEViCE^jCONTROL as necessary. 

Following are two tables. The first, Table 2-1, shows which "groups" of device 
control functions must be set before using each type of device. The second table 
shows which type of characteristics are contained in the groups. For example, 
you must set Group A for RS-232 Input. If you look in Table 2-2, you see that 
Group A indicates the type of parity used with the device. Note that each group 
requires a separate call to DEVICE_CONTRO_, and that you can only set one 
characteristic from each group. If ybu set more than one from the same qroup for 
a particular device, the last one set will apply. 
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TaDle 2-1 

DEVICE_CONTROL FUNCTIONS REQUIRED 
BEFORE USING A DEVICE 

D evi c e Ty pe Dfiwio.fi Nsme Required Groups 

Serial RS-232 for input RS232A or RS232B A, C,D,E,F,G 

Serial RS-232 for output RS232A or RS232B A, e, C, G / H, I 
or printer 

Profile SLOTxCHANy (where J 

x and y are numbers) 
or PARAPORT 

Parallel printer SLOlxCHANy (where I 

x and y are numbers) 
or PARAPORT 

Console screen and MAINCONSOLE or I 

keyboard ALTCONSOLE 

Diskette drive UPPER or LOWER J 

Here is a sample program which shows how a device control parameter is set. 
This program sets the parity attribute for the RS232B port to "no parity". Note 
that the parity attribute only requires that you set cparm.dccode and 
cparm.dcdatafo]. other parameters require that you also set cparm.dcdatafi] and 
cparm.dcdata[2]. They are set in a similar manner. 

VAR 

cparm*. dctype; 
errnum: integer; 
path: pathname; 

BEGIN 

path:= , -RS232B i ; 

cpam.dcversion:=2; (* always set this value *) 

cparm.dccode: = 1; 

cparn . dcdata [ ] : = 0; 

DEVICE_C0NTROL(ermum, path, cparm); 
END; 
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Table 2-2 shows how to set cparm.dccode, cparrn.dcdata[0], cparm.dcdatafl], and 
cparm.dcaata[2] for the various available attributes.. Note that any values In 
cparm.dcdata past eparm.dcdata[2j are ignored when you are setting attributes 
documented here. 

Table 2-2 



FUNCTION 



DEVICE_CONTROL OUTPUT FUNCTIONAL GROUPS 

.decode .qccfateto] .flcaataU] .d c dat a GI 



Group A— Parity. 

No parity l 
Odd parity, no 1 

input parity 

checking 
Odd parity, 1 

input parity 

errors = oo 
Even parity, no l 

Input parity 

checking 
Even parity, l 

input parity 

errors = $80 

Group B-- -output Handshake: 
None 11 

dtr handshake 2 
XON/XOFF handshake 3 
delay after cr, LF 4 

Group c~Baud rate: 



ns delay 
baud 



Group D— Input waiting: 
wait for fun line 6 
return whatever rec'd 6 
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Group E— Input handshake: 
no hand shake 7 

9 

DTR handshake 7 
xon/xoff handshake 8 

Group F~lnput type-ahead Duffer: 

flush only 9 

flush & re-size 9 

flush, re-size, 9 
and set threshold 

Group G— Disconnect Detection: 

none 10 

BREAK detected 10 
means disconnect 




-1 



-1 




non-zero 



Group H— Timeout on output (handshake interval): 



no timeout 
timeout enabled 



12 
12 







seconds 
Group I— Automatic linefeed insertion: 



disable 
enabled 



17 

17 



65 



-1 


-2 


-2 


bytes 


-2 


-2 


bytes 


low 


hi 



Group J— Disk errors (set to l to enable, to to disable): 

enable sparing 21 sparing rewrite reread 

Group K— Break command (never required — available only on 

serial RS-232 devices) 

o 



send break 


13 


millisecond 
duration 


send break 


13 


millisecond 


while lowering 




duration 


DTR 
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Using Group C,you can set baud to. any standard rate. However, 3600, 7200, 
and 19200 baud are available only on the RS232B port. 

'Low* and 'Hi* under Group F set the low and high threshold in the type ahead 
input buffer. When 'hi* or more bytes are in the input buffer XOFF is sent or 
DTR is dropped. Then when 'Low* oi fewer bytes are in the type ahead buffer, 
XON is sent or DTR is re-asserted, j The size of the type ahead buffer (bytes) 
can be any value between and 64 bytes inclusive. 

in Group J, disk sparing, when enabled, orders the device driver to re-locate 
blocks of data from areas of the diskjthat are found to be bad. 

Disk rewrite, when enabled, orders ijne Operating System to rewrite data that 
it had trouble reading, but finally managed to read. This condition is referred 
to as a soft error. 

Disk reread, when enabled, orders the Operating System to read data after 
they are written, to make certain that they were written correctly. 

When sending a break command, shown in Group K, any device control from 
Group A removes the break condition, even if the allotted time has not yet 
elapsed. Also, sending a break will disrupt transmission of any other 
character still being sent. If you want to make certain that enough time has 
elapsed for the last character to b$ transmitted, call WRITEJDATA with a 
single null character (equal to 0) just prior to calling DEVlCE_CONTROL to 
send the break. 

Table 2-3 gives a list of mneumonlb constants that you can use In place of 
explicit numbers when setting decode. These mneumonics are provided solely 
for convenience. 



Tame 


2-3 


Decode dneunonles 


QCCjQOfi 


meuronlc 


l 


dvParity 


2 


dvOutDTR 


3 


dvOutxoN 


4 


dvOutOelay 


5 


dvBaud 


6 


dvInUait 


/ 


dvInDTR 


8 


dvInXON 


9 


dvTypeahd 


10 


dvOiscon 


11 


dvOutNoHS 


12 


no nneunonic 


13 


no pneumonic 


15 


dvErrStat 
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16 dvGetEvent 

17 dvAutoLF 

20 dvoiskstat 

21 dvDiskSpare 

OBTAINING DEVICE CC3NTR0L INFORMATION 

When you use DEVICE_CONTROL to find out information about the current 
state of a particular device, you simply give the pathname for the particular 
device^long with a function code for the type of information you need, and 
the record of type dctype that you supply is returned filled with information. 

There are tnree types of information requests you can make. Note that each 
type only applies to some of the available devices. The request types and the 
returned information are described in Table 2-4. 

Here is a program fragment that gets information about the upper diskette 

VAR 

cparm: dctype; 
errnum: integers- 
path: pathname; 

BEGIN 

path:=' -UPPER* ; 

cparn.acverslon:=2; (* always set this value *) 
cparn. decode : = 20; 
DEViCE_coNTROL(errnua patn, cpam); 
URITELN (dedatafo], dcdatafl], dcdata[2 ], dcdata[3], 
acdata[4], acdata[5], dcdata[6]) 

END; 
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Table 2-4 
Device j information 

dccqde de vi c es ; P CD ATA ( retu rne d) 

15 profiles [0] contains disk error status on 

last hardware error (Table 2-5) 

[1] contains error retry count 

since last system coot 

16 console screen [0] contains numbers - 10, 

and Keyboard which indicate events: 

= no event 

1 = upper diskette inserted 

2 = upper diskette button 

3 = lower diskette inserted 

4 = lower diskette button 

6 = mouse button down 

7 = mouse plugged in 

8 = power button 

9 = mouse button up 
10 = mouse unplugged 

[l] contains the current state 
of certain keys, indicated 
^ set bits (if the bit is 
1,- the key is pressed) (bits 
are numbered from the right) 

= caps lock key 

1 = shift key 

2 = option key 

3 = command key 

4 = mouse button 

5 = auto repeat 

[2] contains X and Y coordinates 
of mouse, X in left 2 
bytes, y in right 2 bytes 

[3] contains timer value,' in 
milliseconds 
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20 profile or [0] contains: 

diskette arlve o = no alsK present 

1 = disk present (but not 

accessed yet) ' 
The following indicate that 
a disk is present, and it 
has been accessed at least 
once. 

2 = bad block track appears 

unformatted 

3 = disk formatted by some 

program other than the 
Operating System 

4 = os formatted disk 
[1] contains: 

= no button press pending 

1 = button press pending, 

disk not yet ejected 
[2] contains number of blocks 
(0-16) (meaningful only 
when dcdata[0] = 4 and for 
diskette) 
[3] contains: 

= both copies of the bad- 

block directory OK 

1 = one copy is corrupt 

(meaningful only when 
dcdata[0] = 4) 
[4] contains: 

= sparing disabled 

1 = sparing enabled 
[5] contains: 

= rewrite disabled 

1 = rewrite enabled 
[6] contains: 

= reread disabled 

1 = reread enabled 

Table 2-5 shows the breakdown of the error code In response to a decode- 15 
Information request. This code is given in cparrn.dcdatafoj. 

The cede is a long integer, and therefore contains four bytes. Each oil in 
every byte but byte has meaning. The bytes are shown in Table 2-5 broken 
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up into alts, with the hits and bytes numbered from the right counting from o, 
as shown in Figure 2-1. In all cases, the meaning attributed to the bit is true if 
the bit is set (equals l). 



b y te 

3 



byte 
2 



byte; 



byte 

I: 




,0 7. 



7. 



.0 7. 



Figure 2-1 
Disk Hard Error codes 



,o 



Tatiie 2-5 
Disk Hard Error Codes 

Byte 3 

7 = Profile received <> S to its last response 

6 = write or write/verlfy| aborted because more than 532 

bytes of data were sent or because profile could not 
read its spare table 

5 = Hosts data is no longer in RAM because profile updated 

its spare table 

4 = SEEK ERROR — unable in 3 tries to read 3 consecutive 

headers on a track. 

3 = CRC error (only set during actual read or verify of 

write/verify, not while trying to read headers after 
seeking) 

2 = tiheout'error (could not find header in 9 revolutions) 

— not set while trying to read headers after seeking 

1 = Not used 

= Operation unsuccessful 
Byte 2 

7 = SEEK ERROR — unable in 1 try to read 3 consecutive 

headers on a track 

6 = Spared sector table overflow (nore than 32 sectors 

spared) 

5 = Not used 

4 = Bao block table overflow (more than 100 baa blocks in 

table) 

3 = Profile unable to read its status sector 

2 = Sparing occurred 

1 = seek to wrong track occurred 
= Not used 
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Byte 1 

7 = Profile nas oeen reset 

6 = Invalid block nunber 

5 = Not used 

4 = Not used 

3 = Not used 

2 = Not used 

l = Not used 

o = Not used 
Byte o 

This byte contains the number of errors encountered when 

rereading a block after any read error. 
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ALLOCATE (Var Ecode : Integer; 

Refnun: integer; ; 
Contiguous : Boolean- 
Count :Longint; 
Var Actual: integer) 

Ecode: Error indicator 

Refnun: Reference ! nunoer of object to be allocated 

space 
Contiguous: True=allocate contiguously 
Count: Number of blocks to be allocated 

Actual: Number of -blocks actually allocated 

use allocate to Increase tne sp^ce allocated to an object, if possible, 
ALLOCATE adds the requested number of blocks to the space available to the 
object referenced by Refnum. The actual number of blocks allocated is 
returned in actual. If contiguous is tfue, the new space is allocated In a single, 
unfragmented space on the disk. This space is not necessarily adjacent to any 
existing file blocks. 

ALLOCATE applies only to objects on block structured devices. An attempt 
to allocate more space to a pipe is successful only if the pipe's read pointer is 
less than or equal to its write pointer. If the write pointer has wrapped 
around, but the read pointer has not> an allocation would cause the reader to 
read invalid and uninitialized data, so the File System returns an error 1186 in 
this case. 
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COMPACT (Var Ecode: Integer; 
Refnun: Integer) 

Ecode: Error indicator 

Refnun: Reference number of object to be compacted 

COMPACT deallocates any blocks after the block that contains the logical 
end of file for the file referenced by refnum. (see Figure 2-1.) COMPACT 
applies only to objects on block structured devices. " As is the case with 
ALLOCATE, compaction of a pipe is legal only if the read pointer is less than 
or equal to the write pointer. If the write pointer has wrapped around, but the 
read pointer has not, compaction could destroy data in the pipe. The File 
System returns an error 1188 in this case. 
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TRUNCATE (Var Ecode -.Integer; 
Refnun: Integer) 

Ecoae : Error Indicator 

Refnun: Reference nurnber of object to be truncated 

TRUNCATE sets the logical end of file indicator to the current position of the 
file marker. Any data beyond the (file marker are lost. TRUNCATE applies 
only to block structured devices, truncation of a pipe can destroy data that 
have been written but not yet read, as the diagram snows, truncate does 
not change PEOF, only LEOF. COMPACT; on the other hand, changes both. 



new 

LEOF 

and 
PEOF 



•TRUNCATE' 



r- COMPACT —i 



new 
PEOF 




File Marker 



LEOF 



old 
PEOF 



Figure 2-2 
The Relationship df COMPACT and TRUNCATE 

In this figure the boxes represent blocks of data. Note that LEOF can point to 
any byte in the file, but PEOF can only point to a block, boundary. Therefore, 
TRUNCATE can reset LEOF to any byte in the file, but COMPACT can only 
reset PEOF to a block boundary. 
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FLUSH ( Var Ecode : Integer; 
Refnum: integer) 

Ecoae: Error indicator 

Refnum: Reference number of destination of I/O 

FLUSH forces all buffered information destined for the object identified by 
refnum to be written out to that object. 

A side effect of flush is that all FS buffers and data structures are flushed (as 
well as the control information for the referenced file). If Refnum Is -1, only 
the global file system is flushed. This is a method by which an application can 
insure that the file system in consistent. 
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SET_SAFETY (Var Ecode : I integer; 
var Path: pathname; 
On_off: Boolean) 

Ecode: Error indicator 

Patn: Name of object containing safety switch 
OnjDff : Set saftey switch (On=true), or clear it 
(Off=false) ! 

Each object in the file system has a "Safety switch" to help prevent accidental 
deletion. If the safety switch is on, the object cannot be deleted. 
SET_SAFETY turns the switch on or off for the object identified by path. 
Processes that are sharing an object should cooperate with each other when 
setting or clearing the safety switch j 
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SET_UORKING_DIR (Var Ecode : Integer; 
var Path: Pathname) 

get_uorking_DIR (Var Ecode: integer; 
Var Path: Pathname) 

Ecode: Error indicator 
Path: working directory name 

The Operating System uses the name of the working directory to resolve 
partially specified pathnames into complete pathnames. 
GET_WORKING_DIR returns the current workinq directory name in Path. 
SET_WORKING_DIR sets the working directory name. 

The following program fragment reports the current name of the working 
directory and allows you to set it to something else: 

VAR WorkingDlr :PathNaroe; 

Errorcode: INTEGER; 
BEGIN 
GET_uoRKiNG_DiR(Errorcode, WorkingDlr); 
IF (ErrorCodeoO) THEN 

writelnc cannot get tne current working directory!') 
ELSE URlTELN('The current working directory is: 

^ workingDlr); 
WRITE ('New working directory name: *); 
READLN( WorkingDlr); 

SET_WORKING_DIR(ErrorCode, WorkingDlr); 
END; 
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RESET_CATALOG (Var ECOde : INTEGER; 
var Path:Patnnaj*E) 

GET_NEXT_ENTRY (Var ECOde : INTEGER; 
var Prefix, 

Entry :E_Nane) 

Ecoae: Error indicator 

Path: Working directory nane 

Prefix: Beginning of file nanes returned 

Entry: Names fron catalog 

RESET_CATALOG and GET_NEXT_ENTRY give a process access to catalogs. 
RESET_CATALOG sets the 'cataiqg file marker' to tne beginning of the 
catalog specified by Path. Path should be a root volume name. 
GET_NEXT_ENTRY then performs sequential reads through the catalog file 
specified in the RESET_CATALOG call and returns file system object names. 
An end of file error code (848) is returned when get_nextjentry reaches 
the end of the catalog. If prefix is non-null, only those entries in the catalog 
that begin with that prefix are returned, if prefix is 'ab', for example, only 
file names that begin with 'AB' are returned. The prefix and catalog marker 
are local to the calling process, so several processes can simultaneously read 
a catalog without affecting each other. 
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MOUNT (Var Ecode -.Integer; 
var VName:E_Name; 
Var Password :E_Nane 
Var Devname:E_Nane) 

unhount (var Ecode: integer; 
Var Vnane:E_nane) 

Ecode: Error indicator 

vnane: voiune name 

Password: Password for device (currently ignored) 

Devnane: Device narce 

MOUNT and UNMOUNT handle access to sequential devices or block 
structured devices. For block structured devices, MOUNT logically attaches 
that volume's catalog to tne file system. The name of the volume mounted is 
returned in the parameter Vname. * 

UNMOUNT detaches the specified volume from the file system. No object, on 
that volume can be opened after UNMOUNT has been called. The volume 
cannot be unmounted until all the objects on the volume have been closed ^y 
all processes using them. 

Devname is the name of the device on which a volume is being mounted. 
Devname should be given without a leading dash (-). 

vname is the name of the volume that was successfully mounted, and is 
returned. 
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PROCESSES 



A process is the entity in the Lisa system that performs work. When you ask the 
Operating System to run a prograrfn, the OS creates a specific instance of the 
program ana its associated data. That instance is a process. 

The Lisa can have a number of processes at any one time, and they will appear to 
be running simultaneously. Although processes can share code and data, each 
process has its own stack. | 

Actually, only one process can use the CPU at a time. Which process is active at 
a particular time is determined oy the scheduler. The scheduler allows each 
process to run until some condition that would slow execution occurs (an I/O 
request, for example). At that time, the running process is saved in its current 
state, and the scheduler checks the pool of ready-to-run processes. When the 
original process later resumes execution, it picks up where it left off. 

The process scheduling state has three possibilities. The process is punning if it 
is actually engaging the attention 'of the CPU. If it is ready to execute, but is 
being held back by the scheduler, the process is ready, A process can also be 
blocked in trie blocked state, the process is ignored by the scheduler. It cannot 
continue its execution until something causes its state to be changed to ready. 
Processes commonly become blocked while awaiting completion of I/O, although 
there are a number of other likely causes. 



3-3 



Operating System Reference Manual for the Lisa 



Processes 



3.1 Process Structure 

A process can use up to 16 data segments and 106 code segments. 

The layout of the process address space for user processes is shown in Figure 3-1. 

Seg# 

+ — 

| Unavailable 

+■ 

1 ! user Code segments 



106 

1 — 

107 



122 



123 

+-- 

124 

+-- 

125 
+ -■ 

126 
+-- 

127 
+ -- 



LDSN 1 

(data segments) 

LDSN 16 

stack 

Shared Intrinsic Unit Data 

Screen 

Reserved 

Reserved 



Figure 3-1 

PROCESS ADDRESS SPACE LAYOUT 

Each process has an associated priority, an integer between 1 and 255. The 
process scheduler usually executes the highest priority ready process. Vr\e higher 
priorities (226 to 255) are reserved for Operating system. 

3.2 Process Hierarchy 

When the system is first started, several system processes exist. At the base of 
the process hierarchy is the root process which handles various internal 
Operating System functions, it has at least three sons, the memory manager 
process, the timer process, and the shell process. 
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The memory manager process handles code and data segment swapping. 

The shell process is a user process which is automatically started when the OS is 
initialized. It typically is a command interpreter, but it can be any program. The 
OS simply looks for the program called SYSTEM.SHELL, and executes it. 

The timer process handles timing functions such as timed event channels. 




Root Process 



Shell 
Process 
Memory Manager 

Process Useir 

Process 



Other User Processes 



Other 



Timer 
Process 



Figure 3-2 
Process ; Tree 

Any other system process (the NetworK Control Process, for example) is a son of 
the root process. 

3.3 Process Creation 

When a process is created, it is placed in the ready state, with a priority equal to 
that of the process which created it Ali the processes created by a given process 
can be thought of as existing in a subtree. Many of the process management calls 
can affect the entire subtree of a process as well as the process Itself. 

3.4 Process Control 

Three system calls are provided for explicit control of a process. These calls 
allow a process to kill, suspend (block), pr activate any other user process in the 
system, as long as the process identifier is known. Process handling calls are not 
allowed on operating system processes. 
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35 Process Scheduling 

Process scheduling is based on the priority established for the process and on 
requests for Operating System services. 

The scheduler generally executes the highest priority ready process, once a 
process is executing, it loses the CPU only under certain circumstances, in 
practice, the CPU is lost when there is some specific request for the process to 
wait (for an event, for example), when there is an I/O request, or when there is a 
reference to a code segment that is not in memory. A process that makes any 
Operating System call may lose the CPU. The process will get the CPU back 
when the Operating System is finished except under the following conditions: 

o The running process requests input or output . The scheduler will 
start the next highest-priority process running while the first 
process waits for the I/O to complete . 

o The running process lowers its priority below that of another ready 
process or sets another process's priority to be higher than its 
own. 

o The running process explicitly yields the CPU to another process . 

o The running process activates a higher priority process . 

o The running process suspends itself. 

o A higher priortity process becomes ready . 

o The running process needs code to be swapped into Piemory . 

o The running process executes an event wait call . 

o The running process calls DELAYjnriE. 

Because the Operating System cannot seize the CPU from an executing process 
except in the cases noted above, background processes should be liberally 
sprinkled with YIELD_CPU calls. 

When the scheduler is invoked, it saves the state of the current process and 
selects the next process to run by examining the pool of ready processes. If the 
new process requires that code or data be loaded into memory, the memory 
manager process Is launched. If the memory manager is already working on a 
process, the scheduler selects the highest priority process in the ready queue that 
does not need anything swapped. 

3.6 Process Termination 

A process terminates normally when it calls terminate_process, when it 
reaches an 'END. 1 statement, when some process calls kill_prccess on it, 
when its father process terminates, or when it runs into an abnormal condition. 
When a process begins to terminate, a sys._terminate exception condition Is 
signalled to the terminating process and all of the processes it has created. Any 
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process can create an exception Handler with the DECLARE_EXCEP_HDL call 
(described in Chapter 5 of this manual), so the process can catch the terminate 
exception and clean up before terminating. The sysjterminate exception 
handier will only be executed once. Thus, if an error occurs while the handler is 
executing, the process terminates immediately. 

Termination involves the following steps: 

1. Signal the SYSJTERMINATE Exception on the terminating 
process. 

2. Execute the user's exception handler (if any). 

3. instruct all sons of the current process to terminate. 

4. Close all open files, data segments, pipes, and event 
channels left open by the iuser process. 

5. Send the SYS_SON_TERM everjt to the father of the terminating 
process if a~local event channel exists. 

6. wait for all the sons to finish termination. 

3.7 A Process Handling Example 

The following programs illustrate the use of many of the process management 
calls described in this chapter. Thq program FATHER creates a son process, and 
lets it run for awhile. It then gives you a chance to activate, suspend, kill, or get 
information about the son. 

PROGRAM Father; ' 

USES (*$U Source:SysCallj0bj*) SysCall; 
VAR Errorcotie : INTEGER; (*error returns from system calls *; 
proc_id::LONGlNT; (* process global identifier *] 
progname: Pathname; (* program file to execute *] 
nullrNameString; (* program entry point *; 
Info_Rec:ProclnfoRec; (* information about process 
i : INTEGER; 
Answer: CHAR; 
BEGIN 

ProgName:='SON.0BJ'; (!* this program is defined below *) 

Null:^ 1 ; 

nAKE_PROCESS(ErrorcooeL Proc_id, ProgName, Null, o); 

IF (Errorcodeoo) n-ENi 

WRITELN( 'Error ',Erjrortx>de, ' during process management. '); 
FOR i:=l TO 15 DO (* idle for awhile *) 

BEGIN 

URITELNC Father executes for a moment.'); 
YIELDjCPU(ErrorCode] FALSE); (* let son run *) 
END; 
WRITE('K(ill S(uspend A(ctivate iCnfo 1 ); 
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READLN(ftnswer); 
CASE Answer OF 

% K\ 'k': KILL_PROCESS(ErrorCode.Proc_Id); 

' S ' , ' s ' : SUSPEND_PROCESS(ErrorCode, Proc_Id, TRUE 

(* suspend family *)); 

'A', 'a* : AcnvATE_PROCESS(ErrorCode y Proc_ld, true 

(* activate family *)); 

'IVi': BEGIN 

INFO_PROCESS(ErrorCode, Proc_Id, Info Rec); 

URITELNC Son" s name is Mnfo__Rec.ProgPathName); 

END; 
END; 
IF (ErrorCodeOO) TVEN 

URITELNC Error ",ErrorCode. ' during process 
management.'); 

END. 

The program SON is: 

PROGRAM Son; 

uses (*$u source :Syscail.Obj*) Syscaii; 
VAR ErrorCode: INTEGER; 
nulliNameString; 

BEGIN 

UHILE TRIE DO- 
BEGIN 

URITELNC son executes for a moment.'); 
YlELD_CPU(ErrorCode,FAL.SE);(*let fatner process run**) 

END; 
END. 
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3.8 Process System Calls 

This section describes all the Operating System calls that pertain to 
process control . A summary of all the Operating System calls can be found 
In Appendix A. The following special types are used in process control 
calls: I 

Pathname! = STRING[255!]; 

Namestring = STRlNG[2b]; 

P_s_eventDlock = A s_eventDlock; 

s_eventolock = T_event_text; 

T_event_text = array [0..size_etext] of longint; 

ProcinfoRec = record i 

pathname; 



progpathname 
globalJLd 

father]ici 
priority 



longint; 

longint; 

1..255; 
state I : (pactive, psuspended, pwaiting); 
data_ini : boolean 
end; 
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MAKE_PROCESS (Var ErrNun: Integer; 
var Proc_ia:Longlnt; 
Var ProgFlle : Pathname; 

var EntryNamerNameString; (* NameStrlng = STRING[20 J *) 
Evnt_chn_ref nun : Integer ) 

ErrNun: Error indicator 

Proc_id: Process identifier (globally unique) 

ProgFile: Process file name 

EntryNane: Program entry point 

Evnt_chnj:efnum: Communication channel between calling 
process and created process 

A process is created when another process calls MAKE_PROCESS. The new 
process executes the program identified tyy the pathname, progf ile. If progfile is 
a null character string, the program name of the calling process is used. A 
globally unique identifier for the created process is returned in procjd. 

Evnt_chn_refnum is a local event channel supplied by the calling process (event 
channels are discussed in Chapter 5 of this manual). The Operating System uses 
the event channel Identified by evnt_chn_refnum to send the calling process 
events regarding the created process (for example, sys_SON_term). if 
evnt_chn_refnum is zero, the calling process is not informed when such events 
are produced. 

Entryname, if non-null, specifies the program entry point where execution is to 
begin, Because alternate entry points have not yet been defined, this parameter 
is currently unused. 

Any error encountered during process creation is reported in ErrNum. 
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TERMINATE _PROCESS( Var ErrNun : integer; 

E vent_ptr : P_s_eventblk ) 

ErrNum: Error indicator 

Event _ptr: Information sent to process's creator 

The life of a process can be ended by TERMlNATE_PROCESS. This call causes a 
SYS_TERM1NATE exception to be isignailed on the calling process and on all of 
the processes it has created. The process can declare its own sys_terminate 
exception handler to handle whatever cleanup it needs to do before it is actually 
terminated by the system. When the terminate exception handler is entered, the 
exception information block contains a longint that describes the cause of the 
process termination: 

Excep_Data[o] = Process called TERniNATE_PR0CE5S 

1 Process executed the 'END.* statement 

2 Process! called KILL_PROCESS on itself 

3 some other process called KILLJTOCESS on 

the terminating process 

4 Father process is terminating 

5 Process! made an invalid system call (that 
, is, an unknown call) 

6 Process; made a system call with an 
invalid! errnun parameter address 

7 Process! aborted due to an error while 
trying to swap in a code or data segment 

8 Process 1 exceeded its maximum specified 
stack size 

9 Process aborted due to possible lock up 
of the system by a data space exceeding 
physical memory size 

10 Process: aborted due to a parity error 

There are an additional twenty-six errors that can be signaled. The entire list is 
shown on the first page of Appendix K 

If the terminating process was created with a communication channel, a 
SYS_SON_TERM event is sent to the terminating process's father. The 
terminating process can; specify the text of the 3Y3_S0N_term with the 
EventjDtr parameter. Note that im first (O'th) longint of the event text is 
reserved by the system. When the event is sent to the father, the OS places the 
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termination cause of tne son process in tne first longint. mis is tne same 
termination cause that was supplied to the terminating process itself in tne 
SYS_TERMINATE exception information block. Any user-supplied data in the 
first longint of the event text is overwritten. 

If a process specifies an event to be sent in the terminate_process call out 
the process was created without a local event channel, no event is sent to the 
father. 

If a process terminates by a means other than calling herminate_process, or 
it specifies a nil Event _ptr in the TERMINATE_PROCESS call, and the process 
was created with a local event channel, an event is sent to the father that 
contains the termination cause in the first longint and zeros in the remaining 
event text. 

P_s_eventblk is a pointer to an s_eventblk. S_eventblk is defined as: 

CONST size_etext = 9; (* event text size - 40 bytes *) 
TYPE t_event_text = ARRAY [0..size_etext] OF Longint; 
s_eventblk = t_event_text; 

If a process calls TERMINATE_PROCESS twice, the Operating System forces it to 
terminate even if it has disabled the terminate exception. 
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INFO_PROCESS (Var ErrNurt: Integer; 
Proc_Id:Longlnt; 
Var iProc_Inf o : ProcinfoRec); 

ErrNum: Error indicator 

Proc_ld: Global identifier of process 
Procjnfo: Information about the process identified by 
Proc_id 

A process can call INF0_PR0CESS to get a variety of information about any 
process known to the Operating System. Use the function MYJD to get the 
Procjd of the calling process. 

ProcinfoRec is defined as*. 

TYPE ProcinfoRec = RECORD 
ProgPathnane : Pathname; 
Global_id -Longint; 
Priority :1..255; 

State : (PActive, FfSuspended, PUaiting); 
Data_in : Boolean 

END; 

Datajn indicates whether the datajspace of the process is currently in memory. 

The following procedure gets Information about a process and displays some of it: 

PROCEDURE DlsplayJCnfoCP^OCjidrLONGINT); 
VAR Errorcode : INTEGER; 

Inf o_Rec : ProcinfoRec; 
BEGIN 

INFO J'ROCESSCErrorCode, Procjd, Inf ojtec); 
IF (Erroreode=100) THEN 

URITELNC Attempt tq display info about nonexistent 

process.') 

ELSE 
BEGIN 

WITH info_Rec DO 

BEGIN 

WRITELNC prograh nane: ^ProgPathName); 
URITELNC global! id: '.GlobalJLd); 
WRITELN(' priority: Apriority); 
WRITEC state: '); 
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case state OF 

PActlve : URITELN( ' active ' ); 
PSuspended : URITELN( ' suspended ' ); 
PWaltlng : VRITCLN( * waiting * ) 
END 
END 
END 
END; 
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kill_process (Var ErrNun: Integer; 
Proc_jd:Longlnt) 

ErrNun: ^ Error indicator 
Proc_id: Process to be killed 

KILL_PROCESS kills the process referred to by procjd and ail of the processes 
in its subtree. The actual termination of the process does not occur until the 
process is in one of the following states: 

o Executing in user mode. 

o Stopped due to a SUSPEND_PROCESS call. 

o stopped due to a delayjime! call. 

o stopped due to a wait_event; CHN or senojevent_chn call, or 
READ_DfVm or WRITE.DATA to a" pipe. 
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suspend_process (Var ErrNun: integer; 

Proc_id:Longlnt; 
Susp_Fanily : Boolean) 

ErrNun: Error indicators 

Proc_ld: Process to be suspended 

Susp_Family: If true, suspend the entire process subtree 

SUSPEND_PROCESS allows a process to suspend (block) any process in the 
system. The actual suspension does not occur until the process referred to ^j 
procjd is in one of the following states: 

o Executing in user node 

o Stopped due to a DELAY JTII1E call 

o Stopped due to a UAIT_EVENT_CHN call 

Neither expiration of the delay time nor receipt of the awaited event causes a 
suspended process to resume execution. SUSPEND_PROCESS is the only direct 
way to block a process. Processes, however, can become blocked during I/O, and 
by the timer (see DELAY_TIME), and for many other reasons. 

If susp_family is true, the Operating System suspends both the process referred to 
by procjd and all of its descendents. If susp_famiiy is false, only the process 
identified by procjd is suspended. 
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Processes 



ACTCVATE_PROCESS(Var ErrNun: Integer; 

Proc_Jd:Longlnt; 
Act_Fanily : Boolean) 



ErrNun: 

Proc_ia: 

Act_Fanily: 

subtree 



Error indicator 

Process to De activated 

If true., | activate the entire process 



To awaken a suspended process/: call ACTIVATE_PROCESS. A process can 
activate any other process in the system. Note that ACTIVATE_PR0CESS can 
only awaken a suspended process. If the process is blocked for some other reason, 
ACTIVATE_PROCE:ss cannot unblock it. If actjamily is true, 
ACHVATE_PROCESS also activates all the descendents of the process referred 
to by procjd. 
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SETPRIORITY_PROCESS( Var ErrNum : Integer; 

Proc_Id:Longlnt; 
New_Priority : Integer) 

ErrNun: Error indicator 

Proc_id: Global id of process 

New_Priority : Process's new priority nunber 

SETPRIORITY_PROCESS changes the scheduling priority of the process referred 
to by procjd to new_prlority. The higher the priority value (which must be 
between l and 225), the more likely the process is to be allowed to execute. 
(Operating System processes execute with priorities between 226 ana 255.) 
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YlELD_CPU(Var ErrNun: Integer; 
To_ftny: Boolean) 

ErrNun: Error indication 

To_flny: Yield to any process, or only higher or equal 
priority 

If To_Any is false, YIELD_CPU caiises the calling process to give the CPU to any 
other ready-to-execute process with an equal or higher priority. If To_Any is 
true, YlELDjCPU causes the calling process to yield the CPU to any other ready 
process. If no such process exists, the calling process simply continues execution. 
Successive yields by processes of! the same priority result in a "round-rohin" 
scheduling of the processes. Background processes should use YIELD_CPU often 
to allow other processes to execute [when they need to. 
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f1Y_ID:Longint 

MYJD is a function that returns the unique global identifier (a longint) of the 
calling process. A process can use MYJD to perform process handling calls on 
itself. 

For example: 

SetPriority_Process(Errnua My_ia 100) 

sets the priority of the calling process to 100. 
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MEMORY MANAGEMENT 

Every process has a set of code and data segments which must be in physical 
memory when those code segments and data segments are used. The translation 
of the logical address used by the process to the physical address used by the 
memory controller to access physical memory is handled by the memory 
management unit (MMU). 

4wl (Data Segments 

Each process has a data segment that the Operating System automatically 
allocates to it for use as a stack. Thei stack segment's internal structures are 
managed directly by the hardware and the Operating System. 

A process can acquire additional data segments for uses such as heaps and 
inter-process communication. These additional data segments can be prlvate(or 
local) data segments or snared data segments. Private data segments can be 
accessed only by the creating process. When the process terminates, any private 
data segments still in existence are destroyed. Shared data segments can be 
accessed by any process that opens those segments, A shared data segment is 
permanent until explicitly killed by a process. 

The Operating System requires that data segments be in physical memory before 
the data are referenced. The scheduler automatically loads all of the data 
segments which the program says it needs. It is the responsibility of the 
programmer to insure that the program declares all its needs by associating itself 
with the needed data segments before they are needed. 

This process of association is called binding. A program can bind a data segment 
to itself in several ways. When a program creates a data segment by using the 
MAKEJDATASEG call, the segment is automatically opened and bound to the 
program. If a program needs to open a segment that was already created by 
another program, the OFENJDATASEG call is used. That call binds the segment 
to the calling process, as well as opening the segment for the process. Since 
there may be times when a process needs to use more data segments than can be 
bound at one time, the UNBIND JDATASEG call is provided, which leaves the 
data segment open, but unbinds it The program can then use BIND_DATASEG to 
bind another data segment to the program. 

The Operating System views all data segments except the stack as linear arrays 
of bytes. Therefore, allocation, access, and interpretation of structures within a 
data segment are the responsibility of th£ program. 

42 The Logical Data Segment Number 

The address space of a process allows up to 16 data segments bound to a process 
at any instant, in addition to the stack. Each bound data segment is associated 
with a specific region of the address space with a Logical Data Segment Number 
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(LDSN). (See Figure 3-1.) While a data segment is bound to the process it is said 
to be a member of the working set of the process. 

The process associates a data segmennt with a specific LDSN in the 
MAKE JDATASEG or OPENJDATASEG call. 

The LDSN, which has a valid range of 1 to 16, is local to the calling process. The 
process uses the LDSN to keep track of where a given data segment can be found. 
More than one data segment can be associated with the same LDSN, but only one 
such segment can be bound to an LDSN at any instant and thus be a member of the 
working set of the process. 

43 Shared Data Segments 

Cooperating processes can share data segments. Shared segments cannot be 
larger than 128 Kbytes in length. As with local data sectments, the segment 
creator assigns the segment a file system pathname. All processes that want to 
share that data segment then use the same pathname. If the shared data segment 
contains address pointers to data within the segment, the cooperating processes 
must also use the same LDSN with the segment This insures that all logical data 
addresses referencing locations within the data segment are consistent for the 
processes sharing the segment 

4.4 Private Data Segments 

Data segments can also be private to a process. In this case, the maximum size of 
the segment can be greater than 128 Kbytes, The actual maximum size depends 
on the amount of physical memory in the machine and the number of adjacent 
LDSN's available to map the segment. The process gives the desired segment 
size and the base LDSN to use to map the segment. The Memory Manager then 
uses ascending adjacent LDSN's to map successive 128 Kbyte chunks of the 
segment The process must insure that enough consecutive LDSN's are available 
to map the entire segment 

Suppose a process has a data segment already bound to LDSIN 2. If the program 
tries to bind a 256 Kbyte data segment to LDSN l, the Operating System returns 
an error because the 256 Kbyte segment needs two consecutive free LDSN's. 
Instead, the program should bind the segment to LDSN 3 and the system 
automatically also uses LDSN 4. 

4.5 Code Segments 

Division of a program Into multiple code segments (swapping units) is dictated by 
the programmer through commands to the compiler and linker. The MMU 
registers can map up to 106 code segments. 
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4.6 Swapping 

When a process executes, the following segments must be in physical memory: 

o The current code segment 

o All the data segments In the process working set (the stack and all 
bound data segments) 

The Operating System insures that this minimum set of segments is in physical 
memory before the process is allowed to execute. If the program calls a 
procedure in a segment not in memory, a segment swap-in request is Initiated. In 
the simplest case, this request only requires the system to allocate a block of 
physical memory and to read in the segment from the disk. In a worse case, the 
request may require that other segments be swapped out first to free up 
sufficient memory. A clock algorithm is used to determine which segments to 
swap out or replace. This process is invisible to the pnxjram. 

0,7 Memory Management Calls 

This section describes all the Operating System calls that pertain to memory 
management A summary of all the Operating System calls can be found in 
Appendix A. The following special typeslare used in memory management calls: 

Pathnane = STRING[255]; 

Tdstype = (dsjhared, dsjarivate); 

Dsinf oRec = Ftecord 

nen_size:longint; 

disc_size : lpnglnt; 

nuptojopea : integer; 

LDSN: integer; 

boundF -.boolean; 

presentF ibodlean; 

creatorF:boolean; 

rwaccess -.boolean; 

segptnlongint; 

volnare:ej\ane; 
end; 
E_nane = string [32]; 
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MftKEJDATASEG (Var ErrNum: Integer; 
Var Segnane:Pathname; 

Men_Size, DiskjSize-.Longlnt; 
Var Ref Nunrlnteger; 
Var SegPtnLonglnt; 
Ldsn: Integer 
Dstype :Tdstype) 

Err Nun: Error indicator 

Segname: Pathname of data segment 

tiem_Size: Bytes of memory to be allocated to data 

segment 
Disk_Size: Bytes on disk to be allocated for swapping 

segment 
RefNum: Identifier for data segment 
SegPtr Address of data segment 

Ldsn: Logical data segment number 

Dstype: Type of dataseg (snared or private) 

l^KE_DATASEG creates the data segment identified by the pathname, 
segname, and opens it for immediate read-write access. Segname is a file system 
pathname. 

The parameter Mem_size determines how many bytes of main memory the 
segment is allocated. The actual allocation takes place in terms of 512 byte 
pages. If the data segment is private (Dstype is ds_private), Mernjize can be 
greater than 128 Kbytes, but you must insure that enough consecutive LDSN's are 
free to map the entire segment 

Disk_size determines the number of bytes of swapping space to be allocated to 
the segment on disk. If Disk_size is less than Mem_size, the segment cannot be 
swapped out of main memory. In this case the segment is memory resident until 
it is killed or until its size in memory becomes less than or equal to its disk_size 
(see SIZEJDATASEG). The application programmer should be aware of the 
serious performance implications of forcing a segment to be memory resident. 
Because the segment cannot be swapped out, a new process may not be able to 
get all of its working set into memory. To avoid thrashing, each application 
should insure that all of its data segments are swappable before it relinquishes 
the attention of the processor. 

The calling process associates a Logical Data Segment Number (LDSN) with the 
data segment. If this LDSN is bound to another data segment at the time of the 
call, the call returns an error. 

Refnum is returned by the system to be used in any further references to the data 
segment. The Operating System also returns segptr, an address pointer to be used 
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to reference the contents of the segment segptr points to the base of the data 
segment. 

Any error conditions are returned in ErrftJum. 

When a data segment is made, it immediately becomes a member of the working 
set of the calling process. You can use UNBIND_DATASEG to free the LDSN. 
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KILLJMTASEG (Var ErrNun: Integer; 
Var Segnane:Pathnane) 

ErrNufi: Error indicator 

Segnane: Name of data segnent to be deleted 

When a process is finished with a shared data segment, it can issue a 
KILL_DATASEG call for that segment (HOLL._DATASEG cannot be used on a 
private data segment) If any process, including the calling process, still has the 
data segment open, the actual deallocation of" the segment is delayed until all 
processes have closed it (see CLOSEJDATASEG). During the interim period, 
however, after a KILL JDATASEG call has been issued but before the segment is 
actually deallocated, no other process can open mat segment 

KILLJDATASEG does not affect the membership of the data segment in the 
working set of the process. The refnum and segptr values are valid until a 
CLOSE_DATASEG call Is issued. 

one important note: Normally, when a data segment is closed, the contents are 
written to disk as a file with the pathname associated with the data segment If, 
however, the program calls KILL_DATASEG on the data segment before closing 
the data segment, the contents of the data segment are not, written to disk, and 
will be lost when the segment is closed. 
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OPENDATASEG ( Var ErriNum: Integer; 
VarSegrrareiPathname; 
Var RefNun:lnteger; 
Var SegPtrrLonglnt; 
Ldsn:: Integer) 

ErrNum: Error indicator 

Segname: Name of data segment to be opened 

RefNum: Identifier for data segment 

SegPtr Pointer to contents of data segment 

Ldsn: Logical data segment number 

A process can open an existing shared d£ta segment with OPENDATASEG. The 
calling process must supply the name pf the data segment (segname) and the 
logical data segment number to be associated with it The logical data segment 
number given must not have a data segrrient currently bound to It. The segment's 
name is determined by the process which creates the data segment; it cannot be 
null. 

The Operating system returns both refnum, an identifier for the calling process 
to use in future references to the data segment and segptr, an address pointer 
used to reference the contents of the segrnent 

When a data segment is opened, it immediately becomes a member of the 
working set of the calling process. The access mode of the newly opened segment 
is Readonly. You can use SETACCESS_0ATASEG to change the access rights to 
Readwrite. You can use lUNBlNDJDATASEG to free the LDSN. 

You cannot u$e OPEN on a private data segment since calling CLOSE on a 
private data segment deletes it 
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CL0SE_DATASEG (Var ErrNum : Integer; 
Ref nun: Integer) 

ErrNum: Error indicator 
Refnun: Data segnent identifier 

CLOSE_DATASEG terminates any use of refnum for data segment operations. If 
the data segment is bound to a Logical Data Segment Numoer, CLOSE JDATASEG 
frees that LDSN. The data segment Is removed from the working set of the 
calling process. Refnum is made invalid. Any references to the data segment 
using the original segptr will have unpredictable results. 

If Refnum ref en to a private data segment, CL0SE_DATASEG also kills the data 
segment, deallocating the memory and disk space used for the data segment If 
refnum refers to a shared data segment, the contents of the data segment are 
written to disk as if FLUSHJDATASEG had been called. (If KILLJDATASEG is 
called before CLOSE JDATASEG, the contents of the data segment are thrown 
away when the last process closes the data segment) 

The following procedure sets up a heap for LisaGraf using the memory 
management calls: 

PROCEDURE initDataSecforLisaGraf (var Errorcade: integer); 

CONST HeapSize=16384; (* 16 KBytes for graphics heap *) 
DiskSlze=16384; 

VAR Heapeuf :LONGINT; (* pointer to heap for LisaGraf *) 
GrafHeap:PathName; (* data segment path name *) 

Heap__Refnun:lNTEGER; (* refnun for heap data seg *) 

BEGIN 

GrafHeap^'grafheap 1 ; 

OPO*_DATASEG(ErrorCode, GrafHeap, Iteapjtef nua HeapBuf , 1); 

IF (Errorcodeoo) THEN 

BEGIN 

URITELNC Unable to open'^Grafheap, •Error is \ 
ErrorCode) 
END 
ELSE 

InitHeap(P0INTCR(Heap6uf ), P0INTER(Heap6uf +HeapSize), 
GHeapError); 
END; 
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FLUSHJWTASEG (Var ErrNUTV 

Refnun:Integer) 

ErrNun: Error indicator 
Refnun: Data segment identifier 

FLUSH JDATASEG writes the contents of the data segment identified by refnum 
to the disk. (Note that CLOSE JDATASEG automatically flushes the data 
segment before closing it, unless KILLJDATASEG was called first) This call has 
no effect upon the memory residence or binding of the data segment 
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SIZEJ5ATASEG (Var ErrNun : Integer; 

Ref nun: Integer; 

DeltattemSize : Longlnt; 
Var NewnewSize:Longlnt; 

DeltaOiskSlze :LongInt; 
Var NewOiskSize-.Longlnt) 

ErrNum: Error indicator 

Ref nun: Data segment identifier 

DeltaliemSize: Amount in bytes of change in memory 

allocation 
NewMemSize: New actual size of segment; in memory 
DeltaDiskSize: Amount in bytes of change in disk 

allocation 
NewDiskSize: New actual disk (swapping) allocation 

SEEJDATASEG changes the memory and/or disk space allocations of the data 
segment referred to by refNum. Both deltaMemSize and deltaDiskSize can be 
eltner positive, negative, or zero. The changes to the data segment take place at 
trie high end of the segment and do not destroy the contents of the segment 
unless data are lost in shrinking the segment Because the actual allocation is 
done in terms of pages (512 byte blocks), the newMemSize and newDiskSize 
returned by SIZE J3ATASEG may be larger than the oldsize plus deltaSize of the 
respective areas. 

If the newDiskSize Is less than the newMemSize, the segment cannot be swapped 
out of memory. The application programmer should be aware of the serious 
performance implications of forcing a segment to be memory resident Because 
the segment cannot be swapped out, a new process may not, be able to get all of 
its working set into memory. To avoid thrashing, each application should insure 
that all of its data segments are swappable before it relinquishes the attention of 
the processor. 

If the necessary adjacent LDSN's are available, SIZEJDATASEG can increase the 
size of a private data segment beyond 128 Kbytes. 
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Memory Management 



INF0_DATASEG (Var ErrNum -.Integer; 
Ref mum: Integer; 
var Dslnf o : Dslnf oRec) 

ErrNum: Error indicator 

Refnum: Identifier of data segment 

Dslnf o: Attributes of data segment 

INFODATASEG returns information: about a data segment to the calling 
process. The structure of the dsinf orec record is: 

RECORD 

rtem_Size:LongInt 
Disc jSize : Longlnt 
NumbOpen : Integer 
Ldsn:Integer 
BoundF: Boolean 
PresentF: Boolean 
CreatorF : Boolean 



RWAccess: Boolean 
END; 



(* Bytes of memory allocated to data segment 

(* Bytes of disk space allocated to segment 

(* Current number of processes with segment open 

(* LDSN for segment binding 

C * True if segment is bound to LDSN of calling proc 

(* True if segment is present in memory 

c * True if the calling process is the creator 

(* of the segment 

(* True if the calling process has Write access 

(*to segment 



% 

»); 
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INFOJLDSN ( Var ErrNuruInteger; 
Ldsn: Integer; 
Var Ref Nun: Integer) 

ErrNum: Error indicator 

Ldsn: Logical data segment nunber 

RefNun: Data segment identifier 

INF0_LDSN returns the refnum of the data segment currently bound to Ldsn. You 
can then use INF0_DATASEG to get information about that data segment. If the 
LDSN specified is not currently bound to a data, segment, the refnum returned is 
-l- 
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INFO_ADORESS (Var ErrNun : Integer;; 

Address.-Longint; 
Var Ref Nun: Integer) 

ErrNum: Error indicator 

Address: The address about which the program needs 

information 
Ref Nun: Oata segment identifier 

This call returns the refnum of the currently bound data segment that contains 
the address given. 

If no data segment is currently bound to the calling process that contains 
the address given, an error indication is returned in ErrNum. 
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MB1_INF0 (Var ErrNum:Integer; 
Var Swapspace; 
Dataspace; 
Cur_codesize; 
naxjcodesize :Longint) 

ErrNum: Error indicator 

Swapspace: Amount, in bytes, of swappable system memory 

available to the calling process 
Dataspace: Amount, in bytes, of system memory that the 

calling process needs for its bound data 

areas, including the process stack and the 

shared intrinsic data segment 
Cur_codesize* Size, in bytes, of the calling segment 
hax_codesize: Size, in bytes, of the largest code segment 

within the address space of the calling 

process 

This call retrieves information about the memory resources used by the calling 
process. 
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SETACCESSJMTASEG (Var ErrNun : Integer; 

Refnurulnteger; 
Readonly : Boolean) 

ErrNun: Error indicator 
Refnun: Data segnent identifier 
Readonly: Access node 

A process can control the kinds of access it is allowed to exercise on a data 
segment with the SETACCESSJDATASEG call. Refnum is the identifier for the 
data segment If readonly is true, an attempt by the process to write to the data 
segment results in an address error exception conditioa To get readwrite access, 
set readonly to false. 
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BIND_DATASEG(Var ErrNun: Integer; 
RefNum: Integer) 

UNBIND JMTASEG(Var ErrNun : Integer; 
RefNum: Integer) 

ErrNun: Error indicator 
RefNun: Data segnent identifier 

BIND JDATASEG binds the data segment referred to by refnum to its associated 
logical data segment numbers). UNBIND JDATASEG unbinds the data segment 
from its LDSN(s). BIND JDATASEG causes the data segment to become a member 
of the current working set. At the time of the BIND„DATASEG call, the 
necessary LDSN(s) m ust not be bound to a different data segment 
UNBIND JDATASEG frees the associated LDSN(s). A reference to the contents 
of an unbound segment gives unpredictable results. OPEN JDATASEG and 
MAKE JDATASEG define which LDSN(s) is associated with a given data segment 
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EXCEPTIONS AND EVENTS 

Processes have several ways to keep Informed about the state of the system. 
Normal process-to-process communication and synchronization employs pipes, 
shared data segments, or events. Abnormal conditions, Including those your 
program may define, eimplay exceptions (interrupts). Exceptions are signals, 
which the process can respond to in a variety of ways under your control. 

5.1 Exceptions 

Normal execution of a process can be interrupted by an exceptional condition 
(such as division by zero or reference to an invalid address). Some error 
conditions are trapped by the hardware and some by the system software. The 
process itself can define and signal exceptions of your choice. 

When an exception occurs, the system first checks the state of the exception. 
The three exception states are: 

o Enabled 

o Queued 

o ignored 

If the exception is enabled, and defined tby the system, the system looks for a user 
defined handler for that exception. If none is found, the system invokes the 
default exception handler which usually aborts the process that generated the 
exception. 

If the exception is enablec&nti it was created by the program, the system invokes 
the associated exception handler. (You create new exceptions by declaring and 
enabling handlers for the exceptioa) 

If the state of the exception is queuectthe exception is placed on a queue. When 
that exception is subsequently enabled, this queue is examined, and the 
appropriate exception handler is invoked. Processes can flush the exception 
queue. 

If the state of the exception is Ignored the system still detects the occurrence of 
the exception, but the exception is neither honored nor queued. Note that 
ignoring a system defined exception wiil have uncertain effects. Although you 
can cause the system to ignore even |the SYS_TERMINATE exception, that 
capability is provided so that your program can clean up before terminating. You 
cannot set your program to ignore fatal errors. 
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Invocation of the exception handler causes the scheduler id run, so it is possible 
for another process to run between the signalling of trie exception and the 
execution of the exception handler. 

5.2 System Defined Exceptions 

Certain exceptions are predefined by the Operating System.. These include: 

o Division by zero (SYS_ZER0_DIV) . Default handler atoorts process. 

o Value out of bounds (that is, range check error) or illegal string 
index (SYS_VALUE_00B) . Default handler aborts process . 

o Arithmetic overflow (SYSJDVERFLOU) . Default handler aborts 
process. 

o Process termination (SYSJTERhlNATE) . This exception is signalled 
when a process terminates, or when there is a bus error, address 
error, illegal instruction, privilege violation, or llll emulator 
error. The default handler does nothing. This exception is 
different from the other system defined exceptions in that the 
program always terminates as soon as the exception occurs, in the 
case of other (non-fatal) errors, the program is allowed to 
continue until the exception is enabled. 

Except where otherwise noted, these exceptions are fatal if they occur within 
Operating System code. The hardware exceptions for parity error, spurious 
interrupt, and power failure are also fatal. 

5.3 Exception Handlers 

A user-defined exception handler can be declared for a specific exception. This 
exception handler is coded as a procedure, but must follow certain conventions. 
Each handler must have two input parameters: Environment_Ptr and 
Exception__Ptr. The Operating System ensures that these pointers are valid when 
the handler is entered. Environment_Ptr points to an area in the stack containing 
the interrupted environment; register contents, condition flags, and program 
state. The handier can access this environment and can modify everything 
except the program counter, register A7, and the supervisor state bit in the 
status register. The Exception_Ptr points to an area in the stack containing 
information about the specific exception. 

Each exception handler must be defined at the global level of the process, must 
return, and cannot have any EXIT or global GOTO statements. Because the 
Operating System disables the exception before calling the exception handler, 
the handler should re-enable the exception before it returns. 

If an exception handler for a given exception already exists when another 
handler is declared for that exception, the old handler becomes disassociated 
from the exception. 
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An exception can occur during the execution of an exception handler. The state 
of the exception determines whether it! is honored^laced on a queue, or ignored. 
If the second exception has the same name as the exception that is currently 
being handled and its state is enabled!, a nested call to the exception handler 
occurs. (The system always disables the exception before calling the exception 
handler, however. Therefore, nested i handler calling will only occur if you 
explicitly enable the exception.) 

There is an "exception occurred" flag for every declared exception; it is set 
whenever the corresponding exception! occurs. This flag can be examined and 
reset Once the flag is set, it remains set until FLUSH_EXECP is called. 

The following program fragment gives ah example of exception handling. 

PROCEDURE Handler(Env_Ptr:pjenvl_blk; 

Data_Ptr :pjexjdata); 
VAR ErrNunrlNTEGERl; 
BEGIN 

( * Env_Ptr points to a record containing the progran counter *) 
(* and all registers . Data_Ptr points to an array of 12 longints *) 
( * that contain the event header and text if this handler is *) 
(* associated with an event-call channel (see below) *) 



ENABLE_EXCEP(ermurt excep_name); 

END; 

BEGIN (* Main program*) 



Excep_nare : = * EndQfDoc " ; 
DECLARE_.EXCEP_HDL(ermua excep _nare, ^Handler); 



SIGNAL_EXCEP(errnua excep_name, excepjdata); 
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At the time the exception handler is invoked, the stack is as shown in Figure 5-1. 

low address 

Link 



Program Counter 



Data Ptr 



Environment Ptr 



Terminate Flag 



Exception Kind 
Function Code (fc) 
Access Address (aa) 
Instruction Register 

Status Register 
Program Counter 



Program Counter 

Status Register 

D0-D7 and A0-A7 



Link 



Program Counter 



Exception Data Block 
(sysjrerminate Exception) 



Exception Environment Block 



high address 

Figure 5-1 
Stack at Exception Handler Invocation 

The Exception Data Block given here reflects the state of the stack upon a 
SYS TERMINATE exception. The term_ex__dai:a record (described in Appendix 
A) gives the various forms the data block can take. The Excepjdnd field (the 
first, or oth, longint) gives the cause of the exception. The status register and 
program counter values in the data block reflect the true (current) state of these 
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values. The same data in the Environment block reflects the state of these 
values at the time the exception was signalled, not the values at the time the 
exception actually occurs. 

For SYS_ZER0JDIV, SYS_VALUE_OOB> and SYSJDVERFLOW exceptions, the 
hard_ex_data record described in Appendix A gives the various forms that the 
data block can take. 

In the case of a bus or address error, the PC (program counter) can be 2 to 10 bytes 
beyond the current instruction. The PC and A7 cannot be modified by the 
exception handler. 

When a disabled exception is re-enabled, a queued exception may be signalled. 
In this case, the exception environment reflects the state of the system at the 
time the exception was re-enabled, not the time at which the exception 
occurred. 

5.4 Events 

An event is a piece of information sent by one process to another, generally to 
help cooperating processes synchronize jtheir activities. An event is sent through 
a kind of pipe called an event channel. The event is a fixed size data block 
consisting of a header and some text. The header contains control information; 
the identifier of the sending process and the type of the event. The header is 
written by the system, not the sender, and is readable by the receiving process. 
The event text is written by the sender; its meaning is defined by the sending and 
receiving processes. 

There are several predefined system event types. The predefined type "user" is 
assigned to all events not sent by the Operating System. 

5.5 Event Channels 

Event channels can be viewed as highertievel pipes. One important difference is 
that event channels require fixed size data blocks, whereas pipes can handle an 
arbitrary byte stream. 

An event channel can be defined globally or locally. A global event channel has a 
globally defined pathname catalogued in the file system, and can be used by any 
process. A local event channel, howeveir, has no name and is known only by the 
Operating System and the process that opened it Local event channels can only 
be opened by user processes as receivers. A local channel can be opened by the 
father process to receive system generated events pertaining to its soa 

There are two types of global and local event channels: event-wait and 
event-call. If the receiving process is not ready to receive the event, an 
event-wait type of event channel queues an event sent to it . An event-call type 
of event channel, however, forces its event on the process, in effect treating tne 
event as an exception. In that case, an exception name must be given when the 
event-call event channel is opened, and an exception handler for that exception 
must be declared. If the process reading the event-call channel is suspended at 
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the time the event is sent, the event is delivered when the process becomes 
active. 

When an event channel is created, the Operating System preailocates enough 
space to the channel for typical interprocess communication. If 
SETC)_EVENTjCHN is called when the channel does not have enough space for 
the event, the calling process is blocked until enough space is freed up. 

If WAIT_EVENT_CHN is called when the channel is empty, the calling process is 
blocked until an event arrives. 

The following code fragments use event-wait channels to handle process 
synchronization. Operating System calls used in these program fragments are 
documented later in this chapter. 

PROCESS A: 



chn_name := 'event jchamelj.'; 

exceptions "; 

receiver := TRUE; 

OPENJEVENTJCHN (errint, cm_nane, refnuml, exception, receiver); 

chn_name := , eventJChannelJ2 , ; 

receiver := FALSE; 

OPEN_EVENTj>t* (errint, chn_nane, refnurc, exception, receiver); 

waitlist. length := 1; 

waitlist. refnum[Q] := refnuml; 

REPEAT 

eventl_ptr A .[0] := agreed_upon_yalue; 

interval. sec := 0; (* send event immediately *) 

interval. msec := 0; 

SEND_EVENTJCHN (errint, ref nun2, eventl_ptr, 
interval, clktime); 

wmTJEVENTJIHN (errint, waitlist, ref num_siginalling, 
event2_ptr); 



(* processing performed here *) 
UNTIL AllDone; 
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PROCESS B: 



chn_nane := 'evemtjchanneljr; 

exception:= "; 

receiver := TRUE; 

0PEN_EVENTJDHN (erring ct¥i_nane, ref nun2, exception, receiver); 

chnjname := 'eventjcnannelj.^ 

receiver := FALSE; 

0PEN__EVENTJCHN (errint, crwi__nane, ref nurcL exception, receiver ); 

waitlist. length := 1; 

waitlist.refnun|[0] := refnuml; 

REPEAT 

event2_ptr*.|[0] := agjeed_iupon_yalue; 

interval. sec := 0; (* serid event imedlately *) 

interval.nsec := 0; 

WAIT_EVENT_CHN (errint, waitlist, ref nun^signalling, 

eventl_ptr); 



(* processing performed here *) 



SENDJEVENTJCHN (errint, ref nunc, event2_ptr, 

interval* clktime); 
UNTIL AllDone; 



The order of execution of the two processes Is the same regardless of the process 
priorities. Process switch always occurs at the WAIT_EVENT_CHN call. 

In the following example using event-call channels, process switch may occur at 
different places in the programs. Process A calls Y1ELD_CPU / which gives the 
CPU to Process B only if Process B is ready to run. 
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PROCESSA 



PROCEDURE Handler(Envj)tr:p_env_blk; 
Datajptr :p_ex_data); 



BEGIN 

event2_ptr*.[0] := agreedjupon_yalue; 



(* processing perfomed here *) 



interval. sec := 0; (* send event irnediately *) 

interval. msec := 0; 

SEND_EVENT_CHN (erring ref nun2, event2_ptr, interval, 

clktine); 
to__any := true; 
YIELD_CPU (errint.to_any); 

END; 

BEGIN (* Main progran*) 



DECLARE_EXCEP_HDL (errint, excep_nare_l. entry point); 

chnname := 'event _channel_l*; 

exceptions excep_nane_l; 

receiver := TRUE; 

0PEN_EVENT_CHN (erring chnjrane, ref nunl, exception, receiver); 

chn_name := 'event_cnannel_2; 

receiver := FALSE; 

exceptions "; 

0PEN_EVENT_CHN (erring chn_nane, ref nun2, exception, receiver); 

SEND_EVENT_CHN (errint. ref nunc. event2j)tr. interval, clktine); 

to_any := true; 

YIELD_CPU (errint, to_any); 
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PROCESS B 



PROCEDURE Handler(Enyj)tr:pjBnvJblk; 
Data_ptr : pnexjdata); 



BEGIN 

event2_ptr A .[0] := agreed;_upon_value; 

(* processing performed here *) 



interval. sec := 0; (* send event immediately *) 

interval. msec := 0; I 

SETOJEVENTJCHN (errint, ref mini, event2_ptr, interval, 

clktine); 
to_any := true; 
YIELDJCPU (errint, tojany); 
END; 



BEGIN (* nain program *) 

DECLARE_EXCEP_HDL (errint, excep_nane_l, entry _point) 

chn_nane := , event_cnannel_r; 

exceptions excep_name_l; 

receiver := FALSE; 

exceptions "; j 

OPENJEVENTJCHN (errint, chn_name, refnuml, exception, receiver ); 

chnnane := i eventjchannel_2 , i 

receiver := TRUE; 

0PEN_EVENT_CHN (erTint, chnjiame, ref nunc, exception, receiver); 



END. 
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5.6 The System Clock 

A process can read the system clock time, convert to local time, or delay its own 
continuation until a given time. The year, month, day, hour, minute, second, and 
millisecond are available from the clock. The system clock is set up through the 
Workshop shell (see the Workshop Liser's Guide for the Lis§. 

5.7 Exception Management System Calls 

This section describes all the Operating System calls that pertain to exception 
management A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in exception management 
calls: 

T_ex_name = STRING[16]; 

Longadr - "longint; 

Tjexjdata = Array [0..11] of longint; 

T_ex__sts = Record 

ex_occurred_f : boolean? 

ex_state:t_ex_state; 

nunexcep : integer; 

hdl_adr: longadr; 
end; 
T_ex_state = (enabled, queued, ignored); 
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DECLARE_EXCEP_HDL ( Var ErrNum: Integer; 

Var Excepj\ane:t_ex_nane; 
Entry jpoint:LongAdr) 

ErrNun: Error indicator 

Excepjraroe: Nane of exception 
EntryjDoint: Address I of exception handler 

DECL/^RE__EXCEP_HDL sets the Operating System so that the occurrence of the 
exception referred to by excep_name causes the execution of the exception 
handler at entry jx>int 

Excepjrame is a character string name with up to 16 characters that is locally 
defined in the process and known only to the process and the Operating System. If 
entry-point is ©NIL, and excep_name specifies a system_exception, the system 
default exception handler for that exception is used, if it is a system-defined 
exception. Any previously declared exception handler is disassociated by this 
call. The exception itself is automatically enabled. 

If some excep_name exceptions are queued up at the time of the 
DECL/>RE_EXCEP_HDL call, the exception is automatically enabled and the 
queued exceptions are handled by the newly declared handler. 

You can call CDECLARE._EXCEP_HDL with an exception handler address of ©NIL 
to disassociate your hairSdler from the exception. If there is no system handler 
defined, and the program signals the exception, it will receive an error 201. 
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DISABLEJEXCEP (Var ErrNum: Integer; 

Var ExcepjTane:t_ex_nane; 
Queue: Boolean) 

ErrNun: Error indicator 

Excep_nane: Name of exception to be disabled 

Queue: Exception queuing flag 

A process can explicitly disable the trapping of an exception by calling 
DIS/*BLE_EXCEP. Excep_name is the name of the exception to be disabled. If 
queue is true and an exception occurs, the exception is queued and is handled 
when it is enabled agaia If queue is false, the exception is ignored. When an 
exception handler is entered, the state of the exception in question is 
automatically set to queued. 

If an exception handler is associated through CPEN__EVENT__CHN with an event 
channel, and DIS/^BLE_EXCEP is called for that exception, then: 

o If queue is false, and if an event is sent to the event 
channel by SEND EVENT CHN, the SENDJBi/ENTjDHN call succeeds, 
but it is equivalent to not calling SEND_EVENT_CHN at all. 

o If queue is true, and if an event is sent to the event 
channel by SENDJEVENT__CHN, the SEhD_EVENT_CHN call succeeds 
and a call to UAIT__EVENT_CHN will receive the event, thus 
dequeing the exception. 
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ENABLEJEXCEP (Var ErrNum: Integer; 

Var Excep-nane:tjexjname) 

ErrNun: Error indicator 

Excep_name: Nane of exception to be enabled 

EN/\BLEJEXCEP causes an exception to be handled again. Since the Operating 
System automatically disables an exception when its exception handler is 
entered (see DISABLE_EXCEP), the exception handler should explicitly 
re-enable the exception before it returns to the process. 
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INFOEXCEP (Var ErrNum: Integer; 

Var Excep_nare:t_exjrame; 
Var Excep__status:t_ex_sts) 

ErrNum: Error indicator 

Excepjname: Nane of exception 
Excep_Status: Status of exception 

INFOJEXCEP returns information about the exception specified by excep_name. 
The parameter excep_status is a record containing information about the 
exceptioa This record contains: 

tjBx_sts = RECORD (* exception status *) 

Ex__occurred_f : Boolean; (exception occurred flag *) 
Ex_state:t_ex__state; (* exception status *) 

Numjexcep : integer; (*no. of exceptions queued *) 
Hdl_adr:Longadr; ("exception handler's address *) 
END; 

Once Ex_occurred__f has been set to true, only a call to FLUSHJEXCEP can set it 
to false. 
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SIGNAL_EXCEP (Var ErrNun:Integer; 

Var Excepj\are:t_ex_nare; 
Var Excep_tfata: t_exjdata) 

ErrNum: Error indicator 

Excepjname: Nane of exception to be signalled 

ExcepjData: Inf ornation ! for exception handler 

A process can signal the occurrence of an exception by calling SIGNAL_EXCEP. 
The exception handler associated with excep_name is entered. It Is passed 
excep_data, a data area containing information about the nature and cause of 
the exception. The structure of this information area is: 

array [0..sizejexdata] of Longint 

SIGNAL_EXCEP can be used for user-defined exceptions, and for testing 
exception handlers defined to handle systen-def ined exceptions. 
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FLUSH_EXCEP (Var ErrNun: Integer; 

Var Excep_nane:t_ex_nane) 

ErrNun: Error indicator 

Excep__nane: Name of exception whose queue is flushed 

FLUSH JEXCEP clears out the queue associated with the exception excep_name 
and resets its "exception occurred" flag. 

5.8 Event Management System Calls 

This section describes all the Operating System calls that pertain to event 
management A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in event management calls: 

Pathname = STRING[255]; 
T_ex_naroe = STRING[16J; 
T_chn_sts = Record 

chn__type :chn_kind; 
nun_events : integer; 
openjrecv : integer; 
open_send : integer; 
ec_nane : pathname; 
end; 
chn_kind = (uait_ec, call_ec); 
T_waltlist = Record 

length: integer; 

refnunrarray [0..10] of integer- 
end; 
P_r_eventdlk = A r_eventblk; 
Rjeventblk = Record 

event_header:t eheader; 
event_text : t_eSent_text; 
end; 
T_eheader = Record 

send_pid:longint; 
event _type : longing- 
end; 
T_event_text = array [Q..9] of longint; 
P_s_eventblk = "s_eventblk; 
S_eventblk = T_event_text; 
Timestrpjjiterval = Record 

sec : longint; 
nsec:()..999; 
end; 
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Tirerec = Record 

year: integer; 
day:1..366; 
hour : -23.. 23; 
minute :t59.. 59; 
second:0..59; 
msec:0.1999; 
end; 
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riftKE_EVENT_CHN (Var ErrNun:Integer; 

Var Event_chn_nane:Pathnane) 

ErrNun: Error indicator 
Event_chn_nane: Pathname of event channel 

MAKEJEVENTjCHN creates an event channel with the name given in 
event_chn_name. The name must be a file system pathname; it cannot be null. 
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KILL_EVENTJCHN (Var ErrNun: Integer 

Var Event_chn_nanp:Pathnare) 

ErrNun: Error Indicator 
Event_chn_nane: Pathname of event channel 

To delete an event channel, call KILLJEVEKT_CHN. The actual deletion is 
delayed until all processes using the event channel have closed it. In the period 
between the KILLJEVElsTTjCHN call and the channel's actual deletion, no 
processes can open it A channel can be deleted by any process that knows the 
channel's name. 
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OPEN_EVENT_CHN (Var ErrNum: Integer; 

Var Event__chn_nane:Patnnone; 
Var Refnuin: Integer; 

Excepjrame : t_ex_nane; 

Receiver:Boolean) 

ErrNun: Error indicator 

Event_chnjnane: Pathname of event channel 

RefNun: Identifier of event channel 

Excep_nane: Exception name,, if any 

Receiver: Access node of calling process 

GPEN_EVENT_CHN opens an event channel and defines its attributes from the 
process point of view. Refnum is returned by the Operating System to be used in 
any further references to the channel. 

Event_chn_name determines whether the event channel Is locally or globally 
defined. If it is a null string, the event channel is locally defined. If 
event_chn_name is not null, it is the file system pathname of the channel. 

Excep_Name determines whether the channel Is an event-wait or event-call 
channel. If it is a null string, the channel is of event- wait type. Otherwise, the 
channel is an event-call channel and excep_name is the name of the exception 
that is signalled when an event arrives in the channel. The excep_name must be 
declared before its use in the CPEN_EVENT_CHN call. 

Receiver is a boolean value indicating whether the process is opening the 
channel as a sender (receiver is false) or a receiver (receiver is true). A local 
channel (one with a null pathname) can be opened only to receive events. Also, a 
call-type channel can only be opened as a receiver. 
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CLOSEJEVENT_CHN (Var ErrNun: Integer; 

Refnumrlnteger) 

ErrNun: Error Indicator 

Refnun: Identifier of event channel to be closed 

CXQSEJEVENTjCHN closes the event channel associated with refnum. Any 
events queued in the channel remain there. The channel cannot be accessed until 
it is opened again. 

If the channel has previously been killed with KILL JEVENTjCHN, you will not be 
able to open it after it has been closed. 

If the channel has not been killed, it can be opened by CPENJEVENT_CHN. 
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INF0JEVENT_CHN (Var ErrNum -.Integer; 

Refnun: integer; 
var Chnj:nfo:t_chn_sts) 

ErrNum: Error indicator 

Refnun: Identifier of event channel 

Chnjnfo: Status of event channel 

I^OjEVENT_CHN gives a process information about an event channel . The 
Operating Systen returns a record, chnjLnfo, with information pertaining 
to the channel associated with refnun. 

The definition of the type of the chn_inf o record is: 



t_chn_sts = 
RECORD 

Chn_type : Chn_kind; 
Num_events : Integers- 
Open jrecv: Integer; 

Qpen_send : integer; 

Ecjrame : pathname; 
END; 



(* event channel status *) 
(* wait_.ec or calljec *) 
(* number of queued events *) 
(* number of processes reading 

channel *) 

(* no. of processes sending to 

this channel *) 
(* event channel name *) 
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WAIT_EVENTJDHN (Var ErrNun: Integer^ 

Var Uait_List:t_waitlist; 
Var RefNun:Integer> 

Event _ptr :pjr_eventDlk) 

ErrNun: Error indicator 

wait_list: Record with array of event channel 

refnuros 
Refnun: Identifier of channel that had an event 

Event j)tr: Pointer to event data 

WAU_EVENT_CHN puts the calling process in a waiting state pending the 
arrival of an event in one of the specified channels. Wait Jist is a pointer to a list 
of event channel identifiers. When an event arrives in any of these channels, the 
process is made ready to execute. Refnum identifies which channel got the 
event and event j)tr points to the event itself. 

A process can wait for any boolean combination of events. If it must wait for any 
event from a set of channels (an OR condition), it should call WAIT_EVEhfT_CHN 
with waitjist containing the list of event channel identifiers. If, on the other 
hand, it must wait for sill the events from a set of channels (an AND condition), 
then for each channel in the set, WAliTjEVENTjCHN should be called with a 
waitjist containing just that channel identifier. 

The structure of t_waitllst is: 

RECORD 

Length : Integer; 

Refnun:Array[0..size_waltlist] of Integer; 
END; 

Event_ptr is a pointer to a record containing the event header and the event text. 
Its definition is: 

P_r_eventblk = A rjevehtblk; 
Rjeventblk = Record 

event _he£der : t__eheader; 
event_tqxt : tjevent__text; 
end; 
T_eheader = Record 

send_pid : longint; 
event_type : longing- 
end; 
T_event_text = array [0..9] of longing- 
Send _pid is the process id of the sender. 
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Currently, the possible event type values are: 

1 = Event sent by user process 

2 = Event sent by system 

When you receive the SYS__SON_TERM event, the first longint of the event text 
contains the termination cause of the son process. The cause is same as that 
given in the SYS JTERMINATE exception given to the son process. The rest of 
the event text can be filled by the son process. 

If you call WAITJEVENTJCHN on an event-call channel that has queued events, 
the event is treated Just like an event in an event-wait channel. If 
WAIT_EVENT_CHN is called on an event-call channel that does not have any 
queued events, an error is returned. 
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auSH_EVENTjDHN (Var ErrNun: Integer; 

Refnun:lnteg0r) 

ErrNun: Error indicator 

Refnun: Identifier of event channel to be flushed 

FLUSH_EVENT_CHN clears out the specified event channel. All events queued 
in the channel are removed. If this is called by a sender, it has no effect 
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SEND_EVENT_CHN (Var ErrNun : Integer; 

Ref nun: Integers- 
Event __ptr : p_s_eventblk; 
Interval : Tinestnp_interval; 
Clktine : Tinejrec) 

ErrNun: Error indicator 

Ref nun: Channel for event 

Event_ptr: Pointer to event data 

Interval: Tiner for event 

Clktine: tine data for event 

SEhJDjEVENTjCHN sends an event to the channel sjpecified by refnum. 
Event_ptr points to the event that is to he sent. The event data area contains 
only the event text; the header is added by the system. 

If the event is of the event-wait type, the event is queued. Otherwise the 
Operating System signals the corresponding exception for the process receiving 
the event. 

If the channel is open ay several senders, the receiver can sort the events by the 
process identifier which the Operating System places in the event header. 
Alternatively, the senders can place predefined identifiers in the event text 
which identify the sender. 

The parameter Interval, indicates whether the event is a timed event. 
Timestmpjnterval is a record containing a second and a millisecond field. If 
both fields are 0, the event is sent immediately. If the second given is less than 0, 
the millisecond field is ignored and the time jrec record is used. If the time in the 
timejrec has already passed, the event is sent immediately. If the millisecond 
field is greater than 0, and the second field is greater than oir equal to 0, the event 
is sent that number of seconds and milliseconds from the present 

A process can time out a request to another process by sending itself a timed 
event and then waiting for the arrival of either the timed event or an event 
Indicating the request has been served. If the timed event is received first, the 
request has timed out A process can also time its own progress by periodically 
sending itself a timed event through an event-call event channel. 

5.9 Clock System Calls 

This section describes all the Operating System calls that pertain to the clock. A 
summary of all the Operating System calls can be found in Appendix A. 
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The following special types are used in plock calls: 

Tirestpp.J.nterval = Record 

sec:longint; 
nsec:0..999; 
erta; 
Timejrec = Record 

year: integers- 
day:!. .36$; 
hour:-23..23; 
minute :t59.. 59; 
second :0.. 59; 
msec:0.;999; 
end; 
Hcwrjrange = -23.. 23 
ninute_range = -59.. 59; 
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DELAYJME (Var ErrNumzInteger; 

Interval : TjLnterval; 
Clktine:Tine_rec) 

ErrNun: Error indicator 

Interval: Oelay timer 

Clktine: Tine information 
DELAYJTIME stops execution of the calling process for the number of SECONDS 
and milliseconds specified in the interval record. If this time period is zero, 
DELAYJTIME has no effect If the period is less than zero, execution of the 
process is delayed until the time specified Dy Clktime. 
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GETJIHE (Var ErrNuri: integer; 

Var Sysjlne:Tine_rec) 

ErrNuri: Error indicator 
Sysjrime: Tine information 

GETJTIME returns the current system clock time in the record Sys_Time. The 
msec field of Sys_Time always contains a on return. 
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SET_LOCALJinE_DIFF (Var ErrNun: Integer; 

Hour:Hourjrange; 
f1inute:tlinute„range) 

ErrNun: Error indicator 

Hour: Number of hours difference from the system 

clock 
Minute: Number of minutes difference from the system 

clock 

SET_LCCAL_TIME_DIFF informs the Operating System of the difference in 
hours and minutes between the local time and the system clock. Hour and 
Minute can be negative. 
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cONVERTjrinE (var ErrNumrlnteger; 

Var SysJlme:Tine_rec; 
Var LocalJlrrecTinejrec; 
To_sys:Boolean) 

ErrNun: Error indicator 

Sysjlne: Systen clock tine 

Localjlne: Local tine 

To_sys: Direction of tine conversion 

CCNVERT_TIME converts between local time and system clock time. 

To_sys is a boolean value indicating which direction the conversion is to go. If it 
is true, the system takes the time data in loeal_time and puts the corresponding 
system time in SysJTime. Otherwise, it takes the time data in SysJTime and puts 
the corresponding local time in localitime. Both time data areas contain the 
year, month, day, hour, nninute, second, and millisecond. 
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Chapter 6 
CONFIGURATION 

6.1 Configuration system calls 6-3 

CARDS_EQUIPPED 6-4 

GET_CONFIG_NAME 6-5 

0SB00TV0L . 6-6 
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CONFIGURATION 

Every Lisa system is configured using the Preferences tool. Preferences places 
the configuration state of the system in a special part of the system's memory 
called parameter memory Although parameter memory is not contained on a 
disk, it is supplied with battery power, so that the contents are kept even when 
the system is turned off. Note that the batteries are charged as long as Lisa is 
plugged in, even if the unit is powered off. Also, the batteries will keep 
parameter memory secured for several hours;, even if line power is lost, in 
addition, every time parameter memory is changed, a copy of the new data is 
made on the boot disk. If the contents of parameter memory are lost, this disk 
copy is automatically restored to parameter memory. 

Since the devices actually connected may differ from the configuration stored in 
parameter memory, three calls are provided that allow procprams to request some 
information about the configuration of the system. 

In addition, two calls are provided to directly read and write the contents of 
parameter memory. 

6.1 Configuration System Calls 

This section describes all the Operating System calls that pertain to 
configuration. A summary of all the Operating System calls can be found in 
Appendix A. Special data types used by configuration calls are defined along 
with the calls. 
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CARDSjEQmPPED (Var Errnun: integer; 

Var ln_slot : Slot^array ) 

Errnun: Error code 

In_slot : Identifies the types of cards configured 

This call returns an array showing the types of cards which are in the various card 
slots. 

The definition of Siot_array is: 

slot_array = array [1. .3] of card_types; 



where: 



card_types = (no_card, 

appie_card, 
n_port_card„ 
net_canL 
laser jcard); 
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(£TJX»* : IG_NmE (Var Ermum-.lnteger; 

Devpostn :Tports; 
Var Devnane:E_name) 

Errnun: Error code 

Devpostn: A port identifier 

Devnane : The nane of the device attached to the port 

This call returns the name of the device configured at the port given in devpostn. 
See GSBOOTVCL for the definition of tports. Type e_name is defined as: 

Ejiame = STRING [32]; 
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0S800TV0L (VarErmun: Integer) : Tports 

Errnun: Error code 

Tports: Identifies the port to which the boot volure is 
attached 

08B00TVCL is a function that returns the identifier for the port attached to the 
boot volume. Note that this port migfjit not be the port configured for the boot 
volume, since it is possible for the user to override the default boot. Note also 
that the port identifier is not the same as the device name. You can use 
GET__CONFIG_NAME to find out the name of the device attached to the port. 

Tports is a set that has tnis definition: 

tports = (uppertwig, lowertyig, parallel, 

SlOtll, SlOtl2, Sl0tl3, Sl0tl4> 

SlOt21, SlOt22. Sl0t23, SlQt24, 

SlOt31, SlOt32, Sl0t33, SlOt34, 

seriala, serialb, ftainjconsole., altjconsole, 

trouse, t_spe£ker, t__extral, t_extra2, 

t_extra3); 
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Appendix A 
OPERATING SYSTEM INTERF ACE 



UNIT syscall; 
INTRINSIC; 

INTERFACE 

CONST 

max_ename = 32; 
max_pathname = 255; 
max_label_size = 128; 
len_exnane = 16; 



(* system call definitions unit *) 



(* maximum length of a file system object name *) 

(* maximum length of a file systen pathname *) 

(* maximum size of a file label, in bytes *») 

(* length of exception name *) 

size_exdata = 11; (* 48 bytes, exception data 

block should have the sane size as r_eventblK, received 

event block *) 



size_etext = 9; (* event text size - 40 bytes 

size_waitlist = 10; (* size of wait list - should be sare as reqptrjlst 



(* exception kind 
call_term = 0; 
ended = 1; 
self _kllled = 2; 
killed = 3; 
fthr_tern = 4; 
bad_syscall = 5; 
bad_errnun = 6; 
swap_error = 7; 
stk_overf low =* 8; 
data_overf low = 9; 
parity_err = 10; 



definitions for , SYS_TERraNATE' exception 
(* process called terminate ^process 
(* process executed 'end* statement 
(* process called killjDrocess on self 
(* process was killed by another process 
(* process's father is terninatlng 
(* process nade invalid sys call - subcode bad 
(* process passed bad address for errnum parn 
(* process aborted due to code: swap-in error 
(* process exceeded max size (+T nnn) of stack 
(* process tried to exceed max data space size 
(* process got a parity error while executing 



def_dlv_zero 

def_value_oob 

def_ovfw 

def_nmij<ey 

defjrange 

def str index 



= 11; (* default handler for dlv zero exception was called 
(* " for value oob exception! 
(* " for overflow exception 
(* M for Ntll key exception 
for , sys_value_oob* excep due to value range err 
for •SYSj/ALUEjJue' excep due to string index err 



12; 
13; 
14; 
15; («• 
16; (* 



bus_error = 21; 
addr_error = 22; 
illg_lnst = 23; 



(* bus error occurred 

(* address error occurred 

(* Illegal instruction trap occurred 







*) 
*) 
*) 
-) 
*) 
*) 
*) 
*) 
*) 
*) 
*) 
-) 

-) 
") 
-) 
*) 
-) 
*) 

*) 
-) 

*) 
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privj/iolation = 24; 
Iine_l0l0 = 26; 
line_llll = 27; 

unexpected__ex = 29; 



(* privilege violation trap occurred 
(* line 1010 emulator occurred 
(* line nil emulator occurred 

(* an unexpected exception occurred 



dlv_zero 

value_oob 

ovfw 

nmij<ey 

valuejrange 

str index 



31; 
32; 
33; 
34; 
35; 
36; 



(*device_control function's*) 



dvParity = 1; 
dvOUtDTR = 2; 
dvOutXON = 3; 
dvOutDelay = 4; 
dvBaud - 5; 
dvlnuait = 6; 

dVlnOTR = 7; 
dvlnxON = 8; 
dvTypeahd = 9; 
dvOiscon = 10; 
dvOutNoHS - 11; 

dvErrstat = 15; 
dvGetEvent = 16; 
dvAutOLF = 17; 
dvOiskStat = 20; 
dvDiskSpare = 21; 



*) 
*) 
*) 







(* exception kind definitions for hardware exception *) 



(* excep kind for value range and string index error *) 
(* Note that these |two cause 'SYSJ/ALUEjDOB' excep *) 



(*RS-232*) 

(*RS~232*) 

(*RS-232*) 

(*RS~232*) 

(*RS-232«) 

(*RS-232, CONSOLE*) 

(*RS-232*) 

(*RS~232*) 

(*RS-232*) 

(*RS-232*) 

(^5^-232*) 

(*PR0FILE*) 

(*CONSOLE*) 

(*RS-232. CONSOLE, PARALLEL PRINTER*) (*not yet*) 

(*DISKETTE, PROFILE*) 

(*DISKETTE, PROFILE*) 



TYPE 

pathname = string [max_pathname]; 
e_name = string [max_ename]; 
namestring = string [20]; 



procinfoRec 

progpathname 

globalJLd 

father_ld 

priority 

state 

data in 

end; 



record 
pathname; 
longint; 
longint; 
1..255; 
(pactive, 
boolean 



psuspended pvteiting); 
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Tdstype = (ds_shared, ds_private); (* types of data segments *) 

dsinfoRec = record 
iWLSlze : longint; 
disc_size: longint; 
nunb_ppen : Integer; 
ldsn : integer; 
boundF : boolean; 
presentF : boolean; 
creatorF : boolean; 
rwaccess : boolean; 
segptr : longint; 
volnane: e__nane; 
end; 



t_ex_nane = string [len_exnane]; 

longadr = "longint; 

t_ex_state = (enabled, queued, ignored); 

p_ex_data = "t_ex_data; 

t_ex_data = array [o..size_exdata] of longint; (* exception data blk 



(* exception name 
(* exception state 



t_ex_sts = record 
ex__occurred_f : boolean; 
ex_state : t_ex_state; 
nun_excep : integer; 
hdl_adr : longadr; 
end; 

p_env_blk = *env_blk; 
env blk = record 



PC 


longing- 


sr 


integer; 


do 


longint; 


di 


longint; 


d2 


longint; 


d3 


longint; 


d4 


longint; 


d5 


: longint; 


d6 


longint; 


d7 


longint; 


ao 


• longint; 


ai 


longint; 


a2 . 


- longint; 


a3 


longint; 


a4 : 


longint; 



(- 
(- 
<• 
(* 



(- 
(* 
<« 



(* exception status 
exception occurred flag 
exception state 
nuctoer of exceptions q'ecl 
handler address 



*) 
-) 
-) 
-) 



environment block to pass to handler «) 



program counter 
status register 
data registers 



- 7 



(* address registers - 7 «) 



fl-3 



Operating system Reference ffanual for We Lisa 



Operating system Interface 



as : longlnt; 
a6 : longint; 
a7 : longlnt; 
end; 

p_term_ex_data = A term_ex_data; 

term_ex_data = record 

case excep__kind : longint of 

caii_tera 

ended, 

self .killed, 

killed, 

fthr_tera 

bad__syscall, 

bad__errnum, 

swap_error, 

stk__overflou, 

data_overflow, 

parity_err : (); (* due to process termination 



(* terminate exception data block *) 



lllg_lnst, 
priv__violation, 
line 1010, 
line_mi, 
def„dlv_zero, 
def value_oob, 
defjwfw," 
def nmi_key 



(* due to illegal instruction, privilege violation 
(* due to line iqiq« nil emulator 



(* terminate due to default nandler for hardware 
exception 
: (sr : integer- 
PC : longint); (* at the time of occurrence 
def range, 
def "str_index (* terminate due to default handler for ' SYS_VALUE_00B ' excep for 



*) 



value range or string index error 
: (value_check : integer; 
upper_bound : integer; 
lower_bound : integers- 
return _pc : longint; 
caller_a6 : longint); 

bus_error, 

addr_error (* due to bus error or address error 

: (fun_field : packed record (* one integer 

filler : 0..$7ff; (* 11 bits 

r_w flag : boolean; 

i_n_flag : boolean; 







*) 
*) 
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f Unicode : 0..7; (* 3 bits *) 

end; 

access_adr : longint; 

inst_register : integer; 

sr.error : integer; 

pc_error : longint); 

end; 

p__hard__ex_data = ~hardjex_data; 

hard_ex_data = record (* hardware exception data block *) 

case~excepj<ind : longint of 

div_zero, value_oob, ovfw 

: (sr : integer; 

pc : longint); 

valuejrange, str_index 

: (value_check : integer- 



upper jDound 

lower_bound 

return_pc 

caller_a6 

end; 



integers- 
integer; 
longint; 
longint); 



accesses = (dread, dwrite, append, private, global jref nun); 

nset = set of accesses; 

ionode = (absolute, relative, sequential); 

UID = record (*unique id**) 

a,b: longint 

end; 

timestnp_interval =* record (* tine interval *) 

sec : longint; (* nunber of seconds *) 

nsec : . .999; (* nunber of nllliseconds within a second *) 
end; 

lnfo_type = (devlce_t, volune_t, obJect_t); 

devtype - (diskdev, pascalbd, seqdev, bitbkt, non_io); 

flietype = (undefined, MDDFfiie, rootcat, freelist, badblocks, sysdata, 

spool, exec, usercat, pipe, bootf ile, swapdata, 
swapcode, ranap, userflie, klliedobject); 

entrytype= (enptyentry, catentry, linkentry, flleentry, plpeentry, ecentry, 

killedentry); 
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fs_lnfo = record 

nane : ejiane; 

dlrjpath : pathnane; 

nachlne_id : longint; 

fsjwerhead : integer; 

result_scavenge : integer; 

case otype : inf o_type of 

device_t, volune_t: ( 

iocnannel : integer; 

devt : devtype; 

slot._no : integer; 

fs_size : longint; 

vol_size : longint; 

blockstructured, mounted : boolean; 

opencount : longint; 

privatedev, renote, lockeddev : boolean; 

nount_pending, unnountjDending : boolean; 

volnane, password : e_nane; 

fsversion, volnun : integer; 

volid : UID; 

backupj/olid : UID; 

blocksize, datasize, clustersize, filecOunt : integer; 

label_slze : integer; 

freecount : longint; 

DTVC, DTCC, DTVB, DTVS : longint; 

naster_copy_id, copy_thread : longint; 

overnount_stanp : UID; 

boot„code : integer; 

boot_environ : integer; 

privileged, write_protected : boolean; 

raster, copy. copy_flag, scaverige_flag : boolean; 

vol__left_nounted : boolean ); 

object_t : ( 

size : longint; 

psize : longint; (* physical file size in bytes *) 

lpsize : integer; (* logical page size in bytes for this file *) 

ftype : filetype; 

etype : entrytype; 

DTC, DTA, DTM, DTB, DTS : longint; 

refnun : integer; 

fnark : longint; 

acnode •. mset; 

nreaders, nwriters, nusers : integer; 

fuid : UID; 
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user_type : integer; 

user_subtype : integer; 

systerc_type : integer; 

eof, safety_on, kswitch : boolean; 

private, locked, protected, naster_flle : boolean; 

file_scavenged, file_closedj)y__os, file_left open: boolean) 

end; 



dctype = record 

dcversion : integer; 

decode : Integer; 

dedata : array [G..9] of longint; 

end; 



t_waltllst = record 

length : integer; 

refnum : array [0..slze_waitllst] of integer; 

end; 



(* user /driver defined data *) 
(* wait list *) 



t_eheader = record 
send_pid : longint; 
event_type : longint; 
end; 



(* event header 

(* sender's process id 

(* type of event 



t_event_text = array [o..size_etext] of longint; 

p_r_eventblk = A r_eventblk; 

r_eventblk = record 

event_header : t_eheader; 

event_text : t_event__text; 

end; 

p_s_eventblk = A s_eventblk; 
s_eventblk = t__event_text; 



(* Julian date *) 



tinejrec = record 
year : integer; 
day : 1..366; 
hour : -23.. 23; 
Minute : -59.. 59; 
second : 0..59; 
msec : 0..999; 
end; 



chn_kind = (wait_ec, call_ec); 

t chn sts = record (* channel status *) 
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chn__type : chn_klnd; (* channel type * 

nun_events : integer; (* nunber of events queued * 

openjrecv : integer; (* nunber of opens for receiving * 

open_send : integer; (* nunber of opens for sending * 

ecjrane : pathnane; (* event channel nane * 
end; 

hour range = -23.. 23; 
nlnutejrange = -59.. 59; 



{configuration stuff: } 

tports = (uppertwig, lowertwig, parallel, 
slotii, slotl2, slotl3, siotH, 

SlOt21, SlOt22, SlOt23, SlOt24, 

SlOt31, SlOt32 y SlOt33, SlOt34, 

seriala, serialb, nain_console, alt_con$ole, 

tjnouse, t__speaker, t_extral, t_extra2, t_extra3); 

card_types = (no_card, apple_card, n_port_card, net_card, laser_card); 

slot_array = array [1..3] of card_types; 

{ Lisa Office systen parameter nenory type } 

pnByteUnique = -128.. 127; 

prienRec = array [l.. 62] of pnByteunlqueFprAllTheDanncryBabies; 



(* File systen calls *) 

procedure MAKEFILE (var ecode: integer; ivar path: pathname; 

label_size : integer); 

procedure MAKE PIPE (var ecode : integer; ivar path: pathnane; 

label_size : lnteger|); 

procedure nAKE_CATALOG (var ecode -.integer; var path: pathnane; 

label_size : integer ); 
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procedure HAKEJ.INK (var ecode: integer; var path, ref :pathnane; 

label_size : integer); 

procedure KILLJ3BJECT (var ecode -.integer; var path: pathname); 

procedure UNKILL_FILE (var ecode: integer; refnun: integer; var 

new_nane:e_nane); 

procedure OPEN (var ecode: integer; var path: pathname; var refnun : integer; 

manip:nset); 

procedure CLOSE J3BJECT (var ecode: integer; refnun: integer); 

procedure READJ3ATA (var ecode : integer; 

refnun : integer; 

data_addr : longint; 

count : longint; 

var actual : longint; 

node : ionode; 

offset : longint); 

procedure WRITE J)ATA (var ecode : integer; 

refnun : integer; 

data_addr : longint; 

count : longint; 

var actual : longint; 

node : ionode; 

offset : longint); 

procedure FLUSH (var ecode -.integer; refnun -.integer); 

procedure LOOKUP (var ecode : integer; 

var path : pathname; 

var attributes : fs_info); 

procedure INFO (var ecode : integer; refnun: integer; var refinfo:fs_inf De- 
procedure ALLOCATE (var ecode : integer; 
refnun : integer; 
contiguous : boolean; 
count : longint; 
var actual : longint); 
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procedure TRUNCATE (var ecode : integer; refnum : integer); 

procedure compact (var ecode : Integer; refnum : Integer); 

procedure rename_entry ( var ecode: integer; var path pathname; var newname : 

e_name ); 

procedure READJ.ABEL ( var ecode : integer; 

var path : pathname; 

data_addr : longint; 

count : longint; 

var actual : longint ); 

procedure WRITE J-ABEL ( var ecode : integer; 

var path : pathname; 

data addr : longint; 

count : longint; 

var actual : longint ); 

procedure MOUNT ( var ecode -.integer; var vname : e_name; var password : 

e_name ;var devname : ejiame); 

procedure unmount ( var ecode: integer; var vname : e_name ); 

procedure SET_WORKING_DIR ( var ecode: integer; var path: pathname ); 

procedure GET__U0RKINGJ)IR ( var ecode .-integer; var path: pathname ); 

procedure setjsafety (var ecode: integer; var path : pathname; on_off -.boolean ); 

procedure DEVICE_control ( var ecode: integer; var path: pathname; 
var cparm : dctype ); 

procedure RESET_CATAL0G (var ecode : integer; var path : pathname); 

procedure get_next_entry (var ecode : integer; var prefix, entry : e_name); 

procedure SET_file_INFO ( var ecode : integer; 
refnum : integer; 
fsi : fs info ^ 
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(* Process Management system calls *) 
function My_ID : longing- 
procedure lnfo_Process (var errnum : integer; proc_id : longint; 
var proc_info : procinfoRec); 

procedure Yield_CPU (var errnum : integer; to_any : boolean); 

procedure setPriority_Process (var errnum : integer; proc_id : longint; 
newjDriority : integer); 

procedure Suspend_Process (var errnum : integer; procjLd : longint; 
susp_family : boolean); 

procedure Activate_Process (var ermun : integer; proc..id : longint; 
act_family : boolean); 

procedure Kill_Process (var errnum : integer; proc_id : longint); 

procedure Termlnate_Process (var ermun : Integer; event j)tr : 

p__s_eventbik); 

procedure Make_Process (var ermun : integer; var proc id : longint; 
var progf lie : pathname; var entryname : namestrlng; 
evnt_chn_refnum : integer); 



(* Memory Management system calls *) 

procedure make_dataseg(var errnum: integer; Vcir segname: pathname; 
mem_size, disc_size: longint; var refnum: integer; 
var segptr: longint; ldsn: integer; dstype: Tdstype); 

procedure kill_dataseg (var errnum : integer; var segname : pathname); 

procedure open_dataseg (var errnum : integer; var segname : pathname; 
var refnum : integer; var segptr : longint; 
ldsn : integers- 
procedure close_dataseg (var errnum : integer; refnum : integer); 



A-ll 



Operating System Reference Manual for the Lisa Operating System Interface 

procedure size_dataseg (var errnun : integer; refnun : integer; 
deltanenslze : longint; var newnensize : longint; 
deltadiscsize: longint; var newdiscsize: longint); 

procedure lnfo__dataseg (var errnun : integer; refnun : integer; 
var dsinfo : dsinfoRec); 

procedure setaccess__dataseg (var errnun : integer; refnun : integer; 
readonly : boolean); 

procedure unblnd__dataseg (var errnun : Integer; refnun : Integer); 

procedure blnd_dataseg(var errnun : integer; refnun : integer); 

procedure infojLdsn (var errnun : Integer; ldsn: integer; var refnun: 

integer); 

procedure flushjdataseg(var errnun: integer; refnun: integer); 

procedure nen_info(var errnun: integer; 
var swapspace, dataspace, 
curjcodesize, nax_codesize: longint); 

procedure info_address(var errnun: integer; address: longint; 
var refnun: integer); 

(* Exception Managenent systen calls *) 

procedure declare__excep_hdl (var errnuni : Integer; 
var excep nane : t_ex_nane; 
entry_point : longadr); 

procedure disable_excep (var errnun : irhteger; 
var excepjiane : t ex_nane; 
queue : boolean); 

procedure enabie_excep (var errnun : integer; 
var excep_nane : t_ex_nane); 

procedure slgnal_excep (var errnun : integer; 
var excep_nane :~t_ex_nane; 
excep_data : t_ex__data); 
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procedure info_excep (var errnum : integer; 
var excepjiame : t_ex_name; 
var excep_status : t_ex_sts); 

procedure flusn_excep (var errnum : integer; 
var excep_name : t_ex_name); 



(* Event Channel management systen calls *) 

procedure make_event_chn (var errnum : integer; 
var event_chn_name : pathname); 

procedure kill_event_chn (var errnum : integer; 
var event_chn_name : pathname); 

procedure open_event_chn (var errnum : integer; 

var event_chn_name : pathname; 

var ref num : integer; 

var excep_name : t_ex_name; 

receiver : boolean); 

procedure close_event_chn (var errnum : integer; 
ref num : integer); 

procedure info_event_chn (var errnum : integer; 

refnum : integer; 

var chnJ.nfo : t_chn_sts); 

procedure wait event chn (var errnum : integer; 
var uaitjList 7 t_waltlist; 
var refnum : integers- 
event _ptr : p_r_eventblk); 

procedure f lush_event_chn (var errnum : integer; 
refnum : integer); 

procedure send_event_chn (var errnum : integer; 
refnum : integer; 
event_ptr : p_s eventblk; 
interval : timestmp_interval; 
elk time : timejrec); 
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(* Tlner functions systen calls *) 

procedure delay_tine (var errnun : integer; 
interval : tinestnp_interval; 
clktlne : tinejrec); 

procedure get_tlne (var errnun : integer; 
var gnt_tine : tine_rec); 

procedure setj.ocal_tine_diff (var errnun : integer; 
hour : hourjrange; 
ninute : ninute_range); 

procedure convert_tine (var errnun : integer; 
var gnt_tine : tinejrec; 
var iocai_tine : tinejrec; 
to_gnt : boolean); 



{configuration stuff} 

function 0SB00TV0L(var error : integer) : tports; 

procedure GET_CONFlG_NAnE( var error : integer; 
devpostn : tports; 
var devnane : e_nane); 

procedure CARDS_EQUTPPED(var error : integer; 
var ln_slot : slot_array); 

IMPLEMENTATION 

procedure nAKE_FILE; external; 
procedure I1AKE_PIPE; external; 
procedure h*AKE_CATALOG; external; 
procedure I1AKEJ-INK; external; 
procedure kill_OBJECT; external; 
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procedure open; external; 
procedure CL0SEJ3BJECT; external; 
procedure read_data; external; 
procedure URITE_DATA; external- 
procedure FLUSH; externals- 
procedure LOOKUP; external; 
procedure INFO; externals- 
procedure ALLOCATE; external; 
procedure TRUNCATE; externals- 
procedure COnPACT; externals- 
procedure RENAHE_ENTRY; external; 
procedure READJ.ABEL; externals- 
procedure URITEJ.ABEL; externals- 
procedure MOUNT; externals- 
procedure untiount; externals- 
procedure SET_W0RKING_DIR; externals- 
procedure GET_UORKING_DIR; externals- 
procedure SET.SAFETY; externals- 
procedure DEVICE_C0NTR0L; externals- 
procedure RESET_CATALOG; externals- 
procedure GET_NEXT_ENTRY; externals- 
procedure GET_DEV_NAtlE; external; 
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function My_ID; external; 
procedure Info_Process; external; 
procedure Yield_CPU; externals- 
procedure SetPriority_Process; external; 
procedure Suspend_Process; externals- 
procedure Activate_Process; externals- 
procedure Klll_Process; externals- 
procedure Terninate_Process; externals- 
procedure flake_Process; externals- 
procedure Sched_ciass; externals- 
procedure nake_dataseg; externals- 
procedure kill_dataseg; externals- 
procedure open_dataseg; externals- 
procedure closejlataseg; externals- 
procedure slzejtetaseg; externals- 
procedure lnfo_dataseg; externals- 
procedure setaccess_dataseg; externals- 
procedure unDind_dataseg; externals- 
procedure Dlnd_dataseg; externals- 
procedure lnfo_ldsn; externals- 
procedure f lusn_dataseg; externals- 
procedure roen_lnfo; external; 
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procedure declare_excep_hdl; external; 
procedure dlsable_excep; external; 
procedure enable_excep; externals- 
procedure slgnai_excep; externals- 
procedure lnfo_excep; externals- 
procedure f lush_excep; externals- 
procedure rcake_event_chn; externals- 
procedure kiil_event_chn; externals- 
procedure open_event_chn; externals- 
procedure close_event__chn; externals- 
procedure info__event_chn; externals- 
procedure wait_event_chn; externals- 
procedure f lusn_event_chn; externals- 
procedure send_event_chn; externals- 
procedure delay_time; external; 
procedure get_tlne; externals- 
procedure set_local_tlme_dlff; externals- 
procedure convert_tlne; externals- 
procedure set_flle_lnfo; externals- 
function ENABLEDBG; external; 
function 0SB00TV0L; external; 
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procedure GET_CONFIG_NAME; externals- 
function DISKJLIKELY; external; 
procedure CARDSJEQUIPPED; external; 
procedure Read_PMeri; externals- 
procedure Uritejwen; externals- 
end. 
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Appendix B 
SYSTEM RESERVED EXCEPTION 

NAMES 



SYS OVERFLOW 



overflow exception. Signalled if the trapv 
instruction is executed, and the overflow condition 
is on. 



SYS VALUE 00B 



value out of bound exception, signalled if the chk 
instruction is executed, and trie value Is less than o 
or greater than upper hound. 



SYS ZERO DIV 



division oy zero exception. Signalled if tne DIVS or 
Dtvu instruction is executed, and the divisor is 
zero. 



SYS TERMINATE 



termination exception. Signalled when a process is 
to he terminated. 
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Appendix C 
SYSTEM RESERVED EVENT 

TYPES 

SYS_SON_TERM "son terminate" event type. If a fatner process has 

created a| son process with a local event channel, this 
event is sent to the father process when the son process 
terminates. 
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Appendix D 

OPERATING SYSTEM ERROR 

MESSAGES 

-1885 Profile not present during driver initialization 

-1882 Profile not present during driver initialization 

-1176 Data in the object has been altered by scavenger 

-1175 File or volume was scavenged 

-1174 File was left open or volune was left mounted, and system crashed 

-1173 File was last closed by the OS 

-1146 Only a portion of the space requested was allocated 

-1063 Attempt to mount boot volume from another Lisa or not most recent boot 

volume 

-1060 Attempt to mount a foreign boot disk following a temporary unmount 

-1059 The bad block directory of the diskette is almost full or difficult 

to read 

-696 Printer out of paper during initialization 

-660 Cable disconnected during Profile initialization 

-626 Scavenger indicated data is questionable, but may be OK 

-622 Parameter memory and the disk copy were both Invalid 

-621 Parameter memory was invalid but the disk copy was valid 

-620 Parameter memory was valid but the disk copy was invalid 

-413 Event channel was scavenged 

-412 Event channel was left open and system crashed 

-321 Data segment open when the system crashed . Data possibly invalid , 

-320 Could not determine size of data segment 

-150 Process was created, but a library used by program has been scavenged & 

altered 

-149 Process was created, but the specified program file has been scavenged 

& altered 

-125 Sepcif led process is already terminating 

-120 specified process is already active 

115 specified process is already suspended 

100 specified process does not exist 

101 Specified process is a system process 

no invalid priority specified (must be l . .225) 

130 could not open program file 

131 File system error while trying to read program file 

132 invalid program file (incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a sysiocal segment for new process 

135 Could not get sysglobal space for new process 
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136 could not set up connunicat Ion channel for new process 
138 Error accessing progran file while! loading 

141 Error accessing a library file while loading progran 

142 Can't run protected file on this machine 

143 Progran uses an intrinsic unit not: found in the intrinsic Library 

144 Progran uses an intrinsic unit whose nane/type does not agree with 
the intrinsic Library 

145 Progran uses a shared segnent not found in the Intrinsic Library 

146 Progran uses a shared segnent whose nane does not agree with te 
intrinsic Library 

147 No space in syslocal for progran file descriptor during process 
creation 

148 No space in the shared IU data segnent for the progran* s shared IU 
globals 

190 No space in syslocal for progran file description during 
List_LibFiles operation 

191 Could not open program file 

192 Error trying to read progran file 

193 Can't read protected progran file 

194 invalid progran file (incorrect fornat) 

195 Progran uses a shared segnent not found in the intrinsic Library 

196 Progran uses a shared segnent whose nane does not agree with the 
intrinsic Library 

198 Disk I/O error trying to read the intrinsic unit directory 

199 specified library file nunoer does [not exist in the Intrinsic 
Library 

201 No such exception nane declared 

202 No space left in the systen data area for declare_execp_hdl or 
signai_excep 

203 Null nane specified as exception nane 

302 Invalid ldsn 

303 No data segnent bound to the ldsn 

304 Data segnent already bound to the ldsn 

306 Data segnent too large 

307 Input data segnent path nane is invalid 

308 Data segnent already exists 

309 Insufficient disk space for data segnent 

310 An invalid size has been specified 

311 Insufficient systen resources 

312 unexpected file systen error 

313 Data segnent not found 

314 Invalid address passed to Info__Address 

315 Operation nay cause a data lockout \ 

317 Disk error while trying to swap in data segnent 
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401 Invalid event channel name passed to make__eventj}hn 

402 No space left in system global data area for open_event_chn 

403 No space left in system local data area for open_event_chn 

404 Non-block structured device specified in pathname 

405 Catalog is full in nake_Event_Chn or 0pen_Event_Chn 

406 No such event channel exists in Kill_Event_Chn 

410 Attempt to open a local event channel to send 

411 Attempt to open event channel to receive when event channel has a 
receiver 

413 Unexpected file system error in 0pen_Event_Chn 

416 Cannot get enough disk space for event channel in open_Event_Chn 

417 Unexpected file system error in Close_Ev€>nt__Chn 

420 Attempt to wait on a channel that the calling process did not open 

421 wait_Event_Chn returns empty because sender process could not 
complete 

422 Attempt to call wait_event_chn on an empty event-call channel 

423 cannot find corresponding event channel after being blocked 

424 Amount of data returned while reading from event channel not of 
expected size 

425 Event channel empty after being unblocked, Wait_Event_Chn 

426 Bad request pointer error returned in wait Event_Chn 

427 wait_List has illegal length specified 

428 Receiver unblocked because last sender closed 

429 Unexpected file system error in Wait_Event_Chn 

430 Attempt to send to a channel which the calling process does not 
have open 

431 Amount of data transferred while writing to event channel not of 
expected size 

432 Sender unblocked because receiver closed in Send_Event_Chn 

433 Unexpected file system error in Send Event_Chn 

440 Unexpected file system error in Make~Event_Chn 

441 Event channel already exists in Make~Event Chn 
445 Unexpected file system error in Kill~Event~Chn 
450 unexpected file system error in Flush Event_Chn 

530 Size of stack expansion request exceeds limit specified for 
program 

531 Can't perform explicit stack expansion due to potential data space 
lock out 

532 insufficient disk space for explicit stack expansion 
600 Attempt to perform i/o operation on non i/o request 
602 No more alarms available during driver initialization 

605 Call to non-configured device driver 

606 Can't find sector on floppy diskette (disk unformatted) 

608 Illegal length or disk address for transfer 

609 call to non-configured device driver 
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610 No more room in Sysglobal for I/O request 

613 Unpermitted direct access to spare track with sparing enabled 
on floppy drive 

614 No disk present in drive 

615 Wrong call version to floppy driye 

616 Unpernitted floppy drive function 

617 Checksum error on floppy diskette 

618 Can't format or write -protected^ or error unclamping floppy 
diskette 

619 No more room in Sysglobal for I/O request 

623 Illegal device control parameters to floppy drive 

625 Scavenger indicated data is bad ; 

630 The tine passed to delay_time, cpnvert_tine, or send_event_chn 
has invalid year 

631 Illegal Timeout request parameter 

632 No memory available to initialize clock 

634 Illegal Timed event id of -1 

635 Process got unblocked prematurely due to process termination 

636 Timer request did not complete successfully 

638 Time passed to delay_time or send_event_chn more than 23 days 
from current time \ " 

639 Illegal date passed to Set Jlrne, i or illegal date from system 
clock in Get jrime 

640 RS-232 driver called with wrong version number 

641 RS-232 read or write initiated with illegal parameter 

642 unimpiemented or unsupported RS-232 driver function 

646 No memory available to initialize RS-232 

647 unexpected RS-232 timer interrupt 

648 Unpermitted RS-232 initialization, or disconnect detected 

649 Illegal device control parameters to RS-232 

652 N-port driver not initialized prior to Profile 

653 No room in sysglobal to initialise Profile 

654 Hard error status returned from drive 

655 Wrong call version to Profile 

656 Unpermitted Profile function 

657 illegal device control parameter to profile 

658 Premature end of file when reading from driver 

659 Corrupt file system header chain | found in driver 

660 Cable disconnected 

662 Parity error while sending command or writing data to Profile 

663 Checksum error or CRC error or parity error in data read 
666 Timeout 

670 Bad command response! from drive I 

671 Illegal length specified (must = !i on input) 

672 Unimpiemented console driver function 
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671 Illegal length specified (must = 1 on input) 

672 Unimplemented console driver function 

673 No memory available to initialize console 

674 Console driver called with wrong version number 

675 Illegal device control 

680 wrong call version to serial driver 

682 Unpermitted serial driver function 

683 No room in sysglobal to initialize serial driver 

685 Eject not allowed this device 

686 No room in sysglobal to initialize n-port card driver 

687 Unpermitted n-port card driver function 

688 wrong call version to n-port card driver 

690 wrong call version to parallel printer 

691 Illegal parallel printer parameters 

692 N-port card not initialized prior to parallel printer 

693 No room in sysglobal to initialize parallel printer 

694 unimpiemented parallel printer function 

695 Illegal device control parameters (parallel printer) 

696 Printer out of paper 

698 Printer offline 

699 no response from printer 

700 Mismatch between loader version number and operating system 
version number 

701 OS exhausted its internal space during startup 

702 Cannot make system process 

703 cannot kill pseudo-outer process 

704 cannot create driver 

706 Cannot initialize floppy disk driver 

707 Cannot initialize the file system volume 

708 Hard disk mount table unreadable 

709 cannot map screen data 

710 Too many slot-based devices 

724 The boot tracks don't know the right file system version 

725 Either damaged file system or damaged contents 

726 Boot device read failed 

727 The OS will not fit into the available memory 

728 SYSTEM. OS is missing 

729 SYSTEM. CONFIG is corrupt 

730 system. os is corrupt 

731 SYSTEM. DEBUG or SYSTEM . DEBUG2 is corrupt 

732 SYSTEM. LLD Is corrupt 

733 Loader range error 

734 Wrong driver is found. ; For Instance, storing a Twiggy loader 
on a Profile 

735 SYSTEM. LLD IS missing 
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736 SYSTEM. UNPACK IS MlSSlng 

737 unpack of system. os with system.unpack failed 

801 loResult <> o on I/O using the Monitor 

802 Asynchronous I/O request not completed successfully 

803 Bad combination of mode parameters 
806 Page specified is out of range I 

809 invalid arguments (page, address, offset, or count) 

810 The requested page could not be \ read in 

816 Not enough sysglobal space for file system buffers 

819 Bad device nurtjer 

820 no space in sysglobal for asynchronous request list 

821 Already initialized I/O for this device 

822 Bad device number 

825 Error in parameter values (Allocate) 

826 No more room to allocate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran into unallocated region) 
835 Invalid s-flle number 

837 unallocated s-file or I/O error 

838 Map overflow: s-file too large 

839 Attempt to compact file past PEOF 
841 unallocated s-file or I/O error 

843 Requested exact fit, but one couldn't be provided 

847 Requested transfer count is <=* 

848 End-of-f ile encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit number (FlushFS) 

854 No free slots in s-list directory (too many s-files) 

855 no available disk space for file! hints 

856 Device not mounted 

857 Empty, locked, or Invalid s-flle 

861 Relative page is beyond PEOF (bad parameter value) 

864 No sysglobal space for volume bitmap 

866 wrong FS version or not a valid Lisa FS volume 

867 Bad unit number (Reaijlount, ReaijJnmount) 

868 Bad unit number (Defjiount, Def Jjnmount) 

869 Unit already mounted (mount)/no unit mounted (unmount) 

870 No sysglobal space for DCB or MDDF (mount) 

871 Parameter not a valid s-flle ID ! 

872 No sysglobal space for s-file control block 

873 Specified file is already open for private access 

874 Device not mounted 

875 invalid s-file ID or s-file control block 
879 Attempt to postion past LE0F 

881 Attempt to read empty file 



D-6 



operating System Reference Manual for the Lisa Error Messages 

882 No space on volume for new data page of file 

883 Attempt to read past LEOF 

884 Not first auto-allocation, but file was ei^npty 

885 Could not update f ilesize hints after a write 

886 No syslocal space for I/O request list 

887 Catalog pointer does not indicate a catalog (bad parameter) 

888 Entry not found in catalog 

890 Entry by that name already exists 

891 Catalog is full or is damaged 

892 Illegal name for an entry 

894 Entry not found, or catalog is damaged 

895 Invalid entry name 

896 Safety switch is on—cannot kill entry 

897 invalid bootdev value 

899 Attempt to allocate a pipe 

900 invalid page count or FCB pointer argument 

901 Could not satisfy allocation request 

921 Pathname invalid or no such device (nakej~ile) 

922 invalid label size (nake_Fiie) 

926 Pathname invalid or no such device (Make_Pipe) 

927 invalid label size (rtake_Pipe) 

941 Pathname invalid or no such device (KilljDbject) 

944 Object is not a file (unkill File) 

945 File is not in the killed state (unkili_Flle) 

946 Pathname invalid or no such device (Open) 

947 Not enough space in syslocal for file system refdb 

948 Entry not found in specified catalog (Open) 

949 Private access not allowed if file already open shared 

950 Pipe already in use, requested access not possible or dwrite not 
allowed 

951 File is already opened in private mode (Open) 

952 Bad refnum (ClosejDbject) 

954 Bad refnum (ReadJJata) 

955 Read access not allowed to specified object 

956 Attempt to position FMARK past LEOF not allowed 

957 Negative request count is illegal (read_data) 

958 Non-sequential access is not allowed (read_data) 

959 System resources exhausted 

960 Error writing to pipe while an unsatisf led read was pending 

961 Bad refnum (write_data) 

962 No WRITE or append access allowed 

963 Attempt to position FnARK too far past LEOF 

964 Append access not allowed in absolute mode 

965 Append access not allowed in relative mode 

966 internal inconsistency of FflARK and LEOF (warning) 
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967 Non-sequential access is not allowed; (wrlte_data) 

968 Bad ref nun (Flush) 

971 Pathname invalid or no such device (Lookup) 

972 Entry not found in specified catalog 
974 Bad ref nun (Info) 

977 Bad ref nun (Allocate) 

978 Page count is non-positive (Allocate) 

979 Not a block structured device (Allocate) 

981 Bad ref nun (Truncate) 

982 No space has been allocated for specified file 

983 Not a block structured device (Truncate) 

985 Bad ref nun (conpact) 

986 No space has been allocated for specified file 

987 Not a block structured device (Conpact ) 

988 Bad ref nun (Fiush_Pipe) 

989 caller is not a reader of the pipe 

990 Not a block structured device (Flush_Pipe) 

994 Invalid ref nun (Set_File__lnf o) 

995 Not a block-structured device (Set_File_lnf o) 

999 Asynchronous read was unblocked before it was satisfied 

1021 Pathname Invalid or no such entry (Reriame_Entry) 

1022 No such entry found (Renane_Entry) 

1023 invalid newnane, check for •-• in string (Renane_Entry) 

1024 New nane already exists in catalog (Renane_Entry) 

1031 Pathnane invalid or no such entry (ReadJ-abel) 

1032 invalid transfer count (Read_Label) 

1033 No such entry found (Readj_abel) 

1041 Pathnane invalid or no such entry (Write_Label) 

1042 invalid transfer count (write _Label) 

1043 No such entry found (Writej_abel) 

1051 no device or voiune by thathane (itount) 

1052 A voiune is already mounted on device 

1053 Attempt to mount temporarily unmounted boot volume Just unnounted from 
this Lisa 

1054 The bad block directory of the diskette is invalid 

1061 no device or voiune by that nane (unnount) 

1062 No volume is nounted on device 

1071 Not a valid or nounted voiune for working directory 

1091 Pathname invalid or no such entry (Set ! safety) 

1092 No such entry found (Set safety) 
lioi invalid device nane (DEVICE_control) 

1121 invalid device, not mounted, or catalog is damaged (Reset_catalog) 
1128 invalid pathnane, device, or voiune not nounted (Get_dev_nane) 

1130 File is protected; cannot open due to protection violation 

1131 No device or voiune by that name 
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1132 No volume is mounted on that device 

1133 No more open files in the file list of that device 

1134 Cannot find space in sysgiobal for open file list 

1135 Cannot find the open file entry to modify 

1136 Boot volume not mounted 

1137 Boot volume already unmounted 

1138 Caller cannot have higher priority than systen processes when 
calling ufcd 

1141 Boot volume was not unmounted when calling rbd 

1142 Some other volume still mounted on the boot device when calling rbd 

1143 No sysgiobal space for rtDDF to do rbd 

1144 Attempt to remount volume which is not the temporarily unmounted 
boot volume 

1145 No sysgiobal space for bit map to do rbd 

1158 Track -by- track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 invalid final shutdown mode 

1162 Power is already off 

1163 Illegal command 

1164 Device is not a Twiggy device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1167 The Device is not blockstructured 

1168 Device name is invalid 

1169 Could not default mount volume before initialization 

1170 could not mount volume after initialization 

1171 '-• is not allowed in a volume name 

1172 No space available to Initialize a bitmap for the volume 

1176 cannot read from a pipe more than half of the allocated physical 
size 

1177 cannot cancel a read request for a pipe 

1178 Process waiting for pipe data got unblocked because last pipe writer 
closed it 

1180 cannot write to a pipe more than half of the allocated physical size 

1181 No system space left for request block for pipe 

1182 Writer process to a pipe got unblocked before the request was 
satisfied 

1183 Cannot cancel a write request for a pipe 

1184 Process waiting for pipe space got unblocked because the reader 
closed the pipe 

1186 Cannot allocate space to a pipe while it has data wrapped around 
1188 Cannot compact a pipe while it has data wrapped around 
1190 Attempt to access a page that is not allocated to the pipe 
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1191 Bad parameter (Flieio) 

1193 Premature end of file encountered! (FilelO) 

1196 Something is still open on deviceh-cannot unmount 

1197 Volume is not formatted or cannot be read 

1198 Negative request count is illegal! 

1199 Function or procedure is not yet implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too Dig 

1212 Error reading boot track program 

1213 Error writing boot track program 

1214 Boot track program file not found 

1215 Can't write boot tracks on that device 

1216 couldn't create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Couldn't find configuration information entry 

1219 Couldn't get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1225 Scavenger has detected an internal inconsistency symptomatic of a 
software bug 

1226 Invalid device name 

1227 Device is not block structured 

1228 Illegal attempt to scavenge the boot volume 

1229 Cannot read consistently from the volume 

1230 Cannot write consistently to the volume 

1231 Cannot allocate space (Heap segment) 

1232 Cannot allocate space (hap segment) 

1233 Cannot allocate space (SFDB segment) 

1237 Error rebuilding the volume root directory 

1240 Illegal attempt to Scavenge a non OS formatted volume 

1296 Bad string argument has been passed 

1297 Entry name for the object is invalid (on the volume) 

1298 s-ilst entry for the object is Invalid (on the volume) 
1807 No disk in floppy drive 

1820 write protect error on floppy drive 

1822 unable to clamp floppy drive 

1824 Floppy drive write error 

1882 Bad response from Profile 

1885 Profile timeout error 
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1998 Invalid parameter address 

1999 Bad refnum 

OPERATING SYSTEM ERROR CODES 

The error codes listed below are generated only when a non-recoverable error 
occurs while in operating system code . The errors are listed by functional 
nodules of the OS . 

SYSTEM ERRORS FOR THE ASYNCHRONOUS CONTROL UNIT 

10050 Request block is not chained to a peb (unblk_req) 

10051 bldjreq is called with interrupts off 

SYSTEM ERRORS IN PROCESS MANAGEMENT 

10701 No space during startup for system segment setup list or global process list head 
(Init_GPList and AllocSys_Segs) 

10100 An error was returned from SetUp_Directory (GetJJnitDir_Entry and 
Change_Directory) 

10101 Couldn ' t find unit BlklO or segment PasLib during Change__Directory 

10102 Error>130 trying to create shell (Root) 

10103 sem_count>l (Init_Sem) 

10104 Couldn' t GetSpace in syslocal for an ObjDescriptor (InitObjFile) 

10105 Couldn' t GetSpace in IU shared data segment after 20 tries (Get_Shared_ptr) 

10197 Automatic stack expansion fault occurred in systen code (Check_Stack) 

10198 Need_mem set for current process while scheduling is disabled 
(SimpleScheduler) 

10199 Attempt to block for reson other than I/O while scheduling isdisabled 
(SimpleScheduler) 

SYSTEMS ERRORS IN EXCEPTION MANAGEMENT 

10200 No space left in system data area in Hard_excep 

10201 Hardware exception occurred while in system code 

10202 No space left from sigl_excep call in hard_excep 

10203 No space left from sigl_excep call in nmi_excep 

10204 Error from inf o_event_chn called in get__evt_num 

10205 Error from wait_event_chn called in excep_prolog 

10207 No system data space in excep_setup 

10208 No space left from sigl_excep call in rangeerror 
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10212 Error in term_def _hdl from enable_excep 

10213 Error in f orce_te'rm_excep, no space in enq__ex_data 

SYSTEM ERRORS IN EVENT CHANNEL MANAGEMENT 

10401 Error f ron close _event_chn in ec_cleanup 

10402 Actual returned from write_datalfor timer event is not correct 

SYSTEM ERRORS IN MEMORY MANAGEMENT 

10579 Unable to swap in OS code segment 

10580 Unagle to get space in Bld_Seg 

10581 Unable to get space in MM_Setup 

10582 Unable to get space in Freeze_Seg 
10590 Fatal parity error 

10593 Unable to move memory manager segment during startup 

10594 Unable to swap in a segment duririg startup 

10595 unable to get space in Extend jiMiist 

10596 Trying to alter size of segment that is not data or stack (Alt_DS_Size) 

10597 Trying to allocate space to an alilocted segment (Allocjlem) 

10598 Attempting to allocate a non-free memory region (Take_free) 

SYSTEM ERRORS IN DRIVER CODE • 

10605 Interrupt from non-configured device 

10609 Interrupt from non-configured device 

10611 Spurious interrupt from Twiggy drive #2 

10612 Spurious interrupt from Twiggy drive #1 *****Duplicate sys error ******** 
10633 Got timeout interrupt with no requests to timeout 

10637 No more "alarms" available for timeout request 

10651 Spurious Profile interrupt 

10695 Spurious Parallel printer interrupt 

10695 Spurious Parallel printer alarm interrupt 

SYSTEM ERRORS IN TIME MANAGEMENT 

10600 Error from make __pipe to make timer pipe 

10601 Error from kill_obJect of the existing timer pipe 

10602 Error from second makejDipe to make timer pipe 

10603 Error from open to open timer pip0 

10604 No syslocal space for head of timer list 
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10610 Error f ron info about tiner pipe 

10612 No syslocal space for timer list element 

10613 Error from read_data of tiner pipe 

10614 Actual returned f ron read_data is not the sane as requested f ron tiner pipe 

10615 Error f ron open of the receiver ' s event channel 

10616 Error f ron write_event to the receiver ' s event channel 

10617 Error f ron close_event__chn on the receiver ' s pipe 
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Appendix E 
FS INFO FIELDS 



DEVICEJ", VOLUMEJT: 
backup_volid 

blocksize 

* blockstructured 
boot_code 
boot_environ 
clustersize 
copy 

copyjlag 
copyjhread 

dataslze 

* devt 

* dir_path 
DTCC 
DTVB 
DTVC 
DTVS 
fllecount 
freecount 
fs_overhead 

fs_size 
fsversion 

* iochannel 

label_size 

$ lockeddev 
machine JD 
master 
master_copyjD 

* mounted 

$ mount pending 

* name 

$ opencount 



ID Qf the volume of which this volume is a 

copy. 

Number of bytes in a block on this device. 

Flag set If this device Is block-structured. 

Reserved. 

Reserved. 

Reserved. 

Reserved. 

Flag set if this volume is a copy. 

Count of copy operations Involving this 

volume. 

Nunriber of data bytes In a page on this 

volume. 

Device type. 

Pathname of the volume/device. 

Date/time volume was created if it Is a copy. 

Date/time volume was last backed-up. 

Date/time volume was created. 

Date/time volume was last scavenged. 

Count of files on this volume. 

Count of free pages on this volume. 

Number of pages on this volume required to 

store file system data structures. 

Number of pages on this volume. 

Version number of the file system under which 

this volume was initialized. 

Number of the expansion card channel 

through which this device is accessed. 

Size! in bytes of the user-defined labels 

associated with objects on this volume. 

Reserved. 

Machine on which this volume was initialized. 

Reserved. 

Reserved. 

Flag; set if a volume Is mounted. 

Reserved. 

Nam$ of this volume/device. 

Count of objects open on this volume/device. 
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overmount_stamp 


Reserved. 


password 


Password of this volume. 


$ prlvatedev 


Reserved. 


privileged 


Reserved. 


$ remote 


Reserved. 


resuit_scavenge 


Reserved. 


scavenge__flag 


Flag set by the Scavenger if it has altered this 




volume in some way. 


* slot_.no 


Number of the expansion slot holding the card 




through which this device is accessed. 


$ unmount jpending 


Reserved. 


volid 


Unique identifier for this volume. 


voljeftjnounted 


Flag set if this volume was mounted during 




a system crash. 


volname 


Volume name. 


volnum 


volume number. 


vol_size 


Total number of blocks in the file system 




volume and boot area on this device. 


write jDrotected 


Reserved. 



* defined for mounted or unmounted devices 
$ defined for mounted devices only 
(all other fields are defined for mounted block-structured devices only) 



OBJECTT: 
acmode 
dlrjDath 

DTA 
DTB 
DTC 
DTM 
. DTS 

eof 

etype 
fiie_closed_by_OS 

file_left_open 

file_scavenged 



Set of access modes associated with this 

refnum. 

Pathname of the directory containing this 

object 

Date/time object was last accessed. 

Date/time object was last backed-up. 

Date/time object was created. 

Date/time object was last modified. 

Date/time object was last scavenged. 

Flag set if end-of-flle has been encountered 

on this object (through the given refnum). 

Directory entry type. 

Flag set if this object was closed by 

the operating system. 

Flag set if this object was open during a 

system crash!. 

Flag set by the Scavenger if this object has 

been altered in some way. 
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fmark 
fs_overhead 

ftype 

fuid 

kswitch 

locked 

lpsize 

machine JD 

master_file 

name 

nreaders 

nwriters 

nusers 
private 

protected 

psize 

refnum 

resuit_scavenge 

safety_on 

size 

system_type 

user_type 

user_subtype 



Absolute byte at which the file mark points. 

Nunrjber of pages used by the file system to 

store control information about this object. 

Objebt type. 

Unique identifier for this object. 

Flagj set when the object is killed. 

Reserved. 

NunHber of data bytes on a page. 

Machine on which this object may be opened. 

Flag! set If this object is a master. 

Entry name of this object 

Number of processes with this object open for 

reading. 

Number of processes with this object open for 

writing. 

Number of processes with this object open. 

Flag set if this object is open for 

private access. 

Flag set if this object is protected. 

Physical size of this object in bytes. 

Reference number for this object (argument 

tolNFO). 

Reserved. 

value of the safety switch for this object. 

Number of data bytes in this object (LEOF). 

Reserved. 

userhdeflned type field for this object 

Use]q-def ined subtype field for this object 
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A 

accessing devices! 1.3 
ACTIVATE_PROCESS : 3 . 8 
ALLOCATE: 2.18 
ALTCONSOLE: 2.1 
attr i bute : 1 .3 

8 _„ 

bi ndi ng: 4.1 
BIND_DATASEGs 4.7 
BITBKT: 2.1 
blocked process: 1.4, 3 

c 

CARDS_EQUIPPED: 6.1 
catalog: 2, 2.1 , 2.19 
clock : 5.6 

- system call s: 5.9 
CL03E_DATASEG: 4.7 
CLOSE_EVENT_CHN: 5.8 
CL0SE_0BJECT: 2.18 
code segment : 4.5 

communication between processes: 1.7 
COMPACT: 2,18 

con-figuration: 6 

- system calls: 6.1 
controlling a device: 2.18 

- a process: 3.4 
CON<v»ERT_TIME: 5.9 
copy i ng a i i 1 e : 2. 18 

creating a data segment <MAKE_DATASEG> : 4.7 

- a process <MAKE_PROCESS> : 3.3, 3.3 

- an event channel <MAKE_EVENT_CHN> : 5.8 

- an object <MAKE_FILE, MAKE_PIPE): 2.18 

D 

data segment, local: 4.1 

- pr I vate : 4.1, 4.4 

- shared: 1 .7 ^ 4.1 , 4.3 

- swapping: 4.6 
decode: 2.18 
dedata: 2.18 
dctype: 2.18 

dc vers ion: 2.18 



DECLARE_£XCEP_HDL: 5.7 
DELAYJTIME: 5.9 
device: 2.3 

- names <prede-f ined) : 2.1 
DE' v 'ICE_CONTROL: 2.19 
directory: 2 
DISABLE_EXCEP; 5.7 

disk hard error codes: 2.18 

E 

enabled exception: 5.1 

ENABLE_EXCEP : 5.7 

end o-f -file, logical: 2, 2.7 

- physical : 2, 2.7 
error messages: D 
event: 1.6, 5, 5.4 

- channel : 1.7, 5.5 

- types: C 

event mangagement system calls: 5.8 
except i on : 1.6, 5 

- enabled: 5.1 

- handlers: 5.3 

- ignored: 5.1 

- names: B 

- queueds 5.1 

exception management system calls: 5.7 

F 

■father process: 1 .4 
■file: 2 

- access: 2.8 

- label : 2, 2.6 

- marker: 2, 2.7 

- name: 2.1 

- private: 2.8 

- shared: 1 .7, 2.8 
■file system: 1.3, 2 

- calls: 2.10 
FLUSH: 2.10 
FLUSH_DATASEG: 4.7 
FLUSH_EVENT_CHN: 5.8 
FLUSH_EXCEP: 5.7 

FS INFO fields: E 



GET_CQNFIG,_NAME: 6.1 
GET_NEXT_ENTRY: 2.18 
GET_.TIME: 5.9 
6ET_W0RKIN6_DIR: 2. IS 
global access to -files: 2.8 

H 

hard error: 2.18 

hierarchy o-f processes: 3.2 

I?J 

ignored exception: 5.1 

INFO: 2.18 

INFO_ADDRESS: 4.7 

INFO_DATASEG: 4.7 

INFO_E<v'ENT_CHN: 5.8 

INF0_EXCE: 5.7 

INF0J.DSN: 4.7 

INF0_PR0CESS: 3.8 

input & output: 2 

interprocess communication: 1.7 

I/O: 2 

K 

KILL_DATASEG: 4.7 
KILL_EUENT_CHN: 5.8 
KILL .OBJECT: 2.18 
KILL .PROCESS: 3.8 

L 

label : 1 .3 

LDSN: 4.2 

LEOF: 2, 2.7 

local data segment: 4.1 

local data segment number: 4.2 

logical end o-f -file: 2, 2.7 

LOOKJJPF: 2.18 

LOWER: 2.1 



M,N 

MAINCONSOLE: 2.1 
MAK£„DATASEG : 4.7 
MAKE„EVENT_CHN : 5.8 
MAKE._FILE: 2.18 
MAKE PIPE: 2.18 



MAKE_PROCESS: 3.8 

MDDFs 2.4 

medium descriptor data -file: 2.4 

memory management: 1.5, 4 

- system cal Is: 4.7 
MEMJNFO: 4.7 

MMU: 4 

MOUNT: 2,18 

mounting a device: 1.3 

MY_ID: 3,8 

naming a dev ice: 1.3 

n am i n g a -file: 1.3 



OPEN: 2.18 
OPEN_DATASEG: 4.7 
0PEN_EVENT_CHN: 5.8 
OS inter-face: A 
0S_B00T_V0L : 6 A 

. P|Q 

page: 2.4 

- descriptor: 2.4 
parameter memory: 6 
PARAPORT: 2.1 
pathname : 1.3 
PEOF: 2, 2.7 

physical end o-f -file: 2, 2.7 

pipe: 1.7, 2.9 

priority o-f devices: 2.3 

private data segment: 4.1, 4.4 

pr i vate -file: 2.3 

process: 1.4, 3 

- blocked: 1 .4, 3 

- control : 3.4 

- creation: 3.3 

- -father: 1 .4 

- hierarchy: 3.2 

- ready: 1.4, 3 

- runn i ng: 1.4, 3 

- schedul i ng: 3.5 

- son : 1.4, 3 

- structure: 3.1 

- termt nated : 1.4, 3 
process system calls: 3.8 



queued exception; 5.1 

ready process: 1.4, 3 
READ_DATA: 2.16 
REAC)_LABEL: 2.18 
re-fnum: 2.8 
RENAME_ENTRY: 2.18 
RESET_CATAL06: 2.18 
RS232A: 2.1 
RS232B: 2.1 
running process: 1.4, 3 

scheduler: 3 

scheduling processes: 3.5 

SEND_EVENT_CHN : 5.3 

SETACCESS_DATASEG : 4 . 7 

SETPRIORITY_PROCESS: 3.8 

SET_FILE_INFQ: 2.18 

SET„LOCAL__TIME_DIFF: 5.9 

SET_SAFETY: 2.18 

SET_WORKING_DIR: 2.18 

shared data segment: 1.7, 4.1, 4.3 

shared -file: 1.7, 2.8 

SIGNAL_EXCEP: 5.7 

SI2E_0ATASEG: 4.7 

SLOTxCHANy: 2.1 

so-ft error: 2.18 

son process: 1 .4 

storage device: 2.3 

structure o-f processes: 3.1 

SUSPEND_PROCESS: 3.8 

swapping: 4.6 

system calls, clock: 5.9 

- con-figuration: 6.1 

- event management: 5.8 

- exception management: 5.7 

- memory management: 4.7 

- process: 3.8 
system clock: 5.6 

system de-fined exceptions: 5.2 
SYS_u\>ERFLOW : B 
SYS_SON_TERM: C 
SYS TERMINATE: B 



SYSJJALUE_008: B 
SYS_2ER0._Dig: B 

terminated process: 1.4, 
TERMINATE_PROCESS: 3.8 
TRUNCATE: 2.16 

y 

UNBIND_DATASEG; 4.7 
UNKILL_FILE: 2.19 
UNMOUNT: 2.18 
UPPER: 2.1 

y 

volume catalog: 2.5 
vol ume name : 1.3 

W ,X , Y , Z • 

WAIT_E'v»ENT_CHN: 5.8 
working directory: 2.2 
WRITE_DATA: 2.16 
WRITE_LABEL: 2.10 
YIELD CPU: 3.8 
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